home *** CD-ROM | disk | FTP | other *** search
/ Amiga Collections: Camelot / Camelot 064 (1990-02)(Swedish User Group of Amiga)(SE)(PD)[WB].zip / Camelot 064 (1990-02)(Swedish User Group of Amiga)(SE)(PD)[WB].adf / cclib / cclib.doc < prev    next >
Text File  |  1990-02-14  |  115KB  |  3,258 lines
  1.  
  2.          Documentation for CClib.library V1.2
  3.  
  4.     Copyright (C) 1989 by Robert W. Albrecht, All Rights Reserved.
  5.  
  6.        Software and Documentation written and distributed by:
  7.  
  8.             Robert W. Albrecht Jr.
  9.             1457 Zion Way
  10.             Ventura, CA 93003, USA
  11.  
  12. -------------------------------------------------------------------------
  13.  
  14.    INTRODUCTION
  15.  
  16.    This is an implementation of the standard C library, with a few extra
  17.    goodies thrown in, that is done as an Amiga loadable library. This
  18.    allows many applications to share the same library code, saving disk
  19.    space, and probably RAM if more than one application is running at a
  20.    time. The other advantage of the library is that as improvements are
  21.    made to it improvements are made to the programs that use it, and the
  22.    programmer doesn't even have to know about it. From the very early Amiga
  23.    days I have thought that this should have been done by CBM, but it
  24.    wasn't, and I was a little suprised that no one else had either. Well,
  25.    after I started I found out why it hadn't been done; It is real tricky
  26.    to make the C library re-entrant. Also it turns out that there are over
  27.    one hundred and forty functions in the library.
  28.  
  29.    My motivation behind doing this project was that I needed a large
  30.    scientific application to be able to run effectivly on a single floppy
  31.    Amiga 500 system, and still have space left over for data files. Since
  32.    the only way to do what I wanted to do was to eliminate the overhead of
  33.    the C library from every program in the package, I had to write this
  34.    library.
  35.  
  36.    THIS IS NOT PUBLIC DOMAIN. You can however create public domain programs
  37.    that use it, but you MUST pay a $50 license fee for Version 2.0 or above
  38.    to use it with commercial software. For the $50 license fee you will
  39.    also get a library used for writing C programs with an "Object Oriented"
  40.    style. This library has objects for Windows, Buttons, Keyins, and many
  41.    more. Also the objects library will allow you to write interactive
  42.    programs much faster, and of better quality, than you could without it.
  43.    Also included in the object library is a help facility that allows the
  44.    user to press the right mouse button and get help for the object the
  45.    mouse pointer is over. So if you are a commercial software developer
  46.    or just a home hobbiest you will want a copy of Version 2.0.
  47.  
  48.    If anyone is interested in translating the software and/or documentation
  49.    to another language, I would be very interested. Please write me at
  50.    the above address if you are interested in the project. We might be
  51.    able to work out some kind of deal where you would get 100% of the
  52.    net receipts for the first 20 licenses, or something like that. I
  53.    would be particularly be interested in German, French, and Italian.
  54.  
  55. -------------------------------------------------------------------------
  56.  
  57.             CONTENTS
  58.  
  59.    I) LICENSE
  60.       Transfer
  61.       Backup Copies
  62.       Term
  63.       Robert W. Albrecht's rights
  64.       Disclaimer of other Warranties, and Liabilities
  65.  
  66.    II) RUN-TIME IMPLEMENTATION OF CCLIB.LIBRARY
  67.    III) FUNCTION DOCUMENTATION
  68.       1) SUPPORT FUNCTIONS
  69.       2) STREAM I/O FUNCTIONS
  70.       3) NON-STANDARD AND LOW-LEVEL I/O FUNCTIONS
  71.       4) CHARACTER TEST MACROS
  72.       5) STRING FUNCTIONS
  73.       6) MEMORY OPERATION FUNCTIONS
  74.       7) FORMAT CONVERSION FUNCTIONS
  75.       8) MEMORY ALLOCATION FUNCTIONS
  76.       9) LINKED LIST FUNCTIONS
  77.       10) SORTING FUNCTIONS
  78.       11) TIME FUNCTIONS
  79.    IV) INSTALLATION
  80.    V) THE NUKELIB PROGRAM
  81.    VI) RELEASE INFORMATION
  82.    VII) NOTES ON LATTICE C
  83.    VIII) REVISION HISTORY
  84.    IX) COPYRIGHTS AND TRADEMARKS
  85.  
  86. -------------------------------------------------------------------------
  87.  
  88.       I) LICENSE
  89.  
  90.       Robert W. Albrecht is the exclusive owner of the enclosed Software
  91.       and Documentation. You are granted non-exclusive license to use the
  92.       Software and Documentation, but you are not the owner of them.
  93.      Your right to use the Software and Documentation under this
  94.       agreement is the "License". "You" means the individual or legal
  95.       entity whose agent receives this software and accepts this Agreement.
  96.       "Software" means the computer program recorded on the floppy-disk or
  97.       other media, any update to them Robert W. Albrecht may later provide
  98.       you, and any back-up copies made. "Documentation" means the user
  99.       manual and other materials packaged with this Software.
  100.  
  101.                 Transfer
  102.  
  103.       You may transfer the license for the use of the Software or
  104.       Documentation to another person free of charge. No charge may
  105.       be made for the Software or Documentation, this includes Public
  106.       Domain Disks and Shareware Disks. If you are the distributor of
  107.       Public Domain disks and you wish to distribute the software at
  108.       a nominal charge please send a stamped self-addressed envelope
  109.       along with a letter stating your intent to the above address, all
  110.       reasonable requests will be granted. Also this version of
  111.       CClib.library can NOT be distributed with commercial software.
  112.       In order to distribute CClib.library with your commercial software
  113.       you MUST pay the one time $50 license fee for Version 2.0 or above
  114.       of CClib.library.
  115.  
  116.               Backup Copies
  117.  
  118.          Make as many copies as you want.
  119.  
  120.                   Term
  121.  
  122.       The license is effective for twenty (20) years from the time you
  123.       receive the software. You may terminate the license at any time by
  124.       returning all software and documentation.
  125.  
  126.             Robert W. Albrecht's rights.
  127.  
  128.       The CClib.library Software and Documentation is protected by copyright,
  129.       trade secret and trademark laws. You may not disclose the Software or
  130.       Documentation to others, except as allowed in this license agreement,
  131.       or remove or alter ownership, trademark and copyright notices on
  132.       Documentation or Software. YOU MUST MAKE A GOOD FAITH EFFORT TO
  133.       PREVENT ANY UNAUTHORIZED USE, COPYING, OR DISCLOSURE OF THE SOFTWARE
  134.       OR DOCUMENTATION. THESE OBLIGATIONS WILL SURVIVE ANY TERMINATION OF
  135.       THE LICENSE AGREEMENT.
  136.  
  137.          Disclaimer of other Warranties, and Liabilities.
  138.  
  139.       THERE ARE NO WARRANTIES, EITHER EXPRESSED OR IMPLIED, FOR THE
  140.       SOFTWARE OR DOCUMENTATION, WHICH ARE BOTH LICENSED TO YOU "AS IS".
  141.       ROBERT W. ALBRECHT EXPRESSLY DISCLAIMS ANY WARRANTY AS TO THE
  142.       PERFORMANCE OF THE SOFTWARE, OR DOCUMENTATION. HE ALSO DISCLAIMS ALL
  143.       OTHER WARRANTIES, INCLUDING (WITHOUT LIMITATION) IMPLIED WARRANTIES
  144.       OF MERCANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  145.       SHALL ANYONE INVOLVED IN THE CREATION, PRODUCTION, OR DISTRIBUTION,
  146.       OF THE SOFTWARE OR DOCUMENTATION BE LIABLE FOR ANY INDIRECT, SPECIAL,
  147.       INCEDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM THE USE OF THE
  148.       SOFTWARE OR DOCUMENTATION OR ARISING FROM ANY BREACH OF ANY WARRANTY.
  149.       Some states do not allow the exclusion or limitation of implied
  150.       warranties or liability for incedental or consequential damages so
  151.       the above exclusion and limitation may not apply to you. IN ADDITON
  152.       TO THE ABOVE LIMITATION, OUR LIABILITY TO YOU OR TO ANYONE ELSE FOR
  153.       DAMAGES SHALL NOT EXCEED THE LICENSE FEE PAID BY YOU FOR THE SOFTWARE
  154.       AND DOCUMENTATION.
  155.  
  156. -------------------------------------------------------------------------
  157.  
  158.    II) RUN-TIME IMPLEMENTATION OF CCLIB.LIBRARY
  159.  
  160.    The implementation of this library is designed to be as transparent as
  161.    possible to the C programmer, but is good to be aware of the actions that
  162.    are taken by the library accomplish this.
  163.  
  164.    The actual code for most of the standard C library functions is in the
  165.    file CClib.library. This is a standard Amiga dynamic link library (DLL)
  166.    and can be shared by many application programs at the same time. For the
  167.    library to work correctly it must be installed in the LIBS: directory of
  168.    your system disk.
  169.  
  170.    DLL's on the Amiga are accessed through the OpenLibrary and CloseLibrary
  171.    system (Exec) functions. When a library is opened with the OpenLibrary
  172.    function, and it is not yet loaded into RAM, Amiga DOS will go to the
  173.    LIBS: directory and load the library specified in the OpenLibrary
  174.    function. The OpenLibrary function will return the memory location of
  175.    the Library structure for the requested library, this is called the
  176.    Library Base Pointer (LBP). A table of jump instructions is located at a
  177.    negative offset to the LBP and the actual functions in the library are
  178.    accessed through this table. For each function in CClib.library there is
  179.    a connection routine in CClib.lib that will allow the application
  180.    program access to the functions in the library. The connection routines
  181.    contain two 68000 instructions: move the LBP into address register A6,
  182.    and jump to an entry in the table of jump instructions in the library.
  183.    The offset from the LBP that gets jumped to in the DLL depends on the
  184.    specific function in the library. All of these details are, of course,
  185.    transparent to the normal user of CClib.library. In order to make the
  186.    interface to the C language more efficient, the convention of placing
  187.    arguments to functions in registers was not used. Instead the
  188.    C calling convention of placing arguments on the stack in reverse
  189.    order was followed. This greatly simplified the connection routines
  190.    that get linked into your application.
  191.  
  192.    To create an implementation of the C library that is as transparent as
  193.    possible to the application the _main function, or initialization code,
  194.    and the _exit function, had to be re-written such that the _main
  195.    function opens the C library and the _exit function closes the C
  196.    library. For this reason these routines could not be included in the
  197.    DLL. You must link with the special version of _main and _exit that are
  198.    contained in the file _main.o. The _main routine must also set up stdin,
  199.    stdout, and stderr for the application, as well as handle the Amiga
  200.    Workbench environment. Also if your program needs access to functions in
  201.    the DLL that use floating point numbers the _main routine must open the
  202.    IEEE floating point library and give a pointer to this library to
  203.    CClib.library. As you may know there are a number of different floating
  204.    point options on the Amiga.
  205.  
  206.    In order to implement floating point operations in the DLL it was
  207.    necessacary to choose just one of the possible floating point options of
  208.    the Amiga. The one that is used by the DLL is the
  209.    MathIeeeDoubBas.library. The reason for using this one is that it is has
  210.    standard 64 bit IEEE floating point numbers and there is a version of
  211.    this library for the 68881 and 68882 MPUs. This means that users of
  212.    Aztec C will have to link with ma32.lib if there are any floating point
  213.    operations in the application. For users of the DLL who will have no
  214.    need for floating point numbers in their application the global short
  215.    integer _math can be declared with a value of zero and
  216.    MathIeeeDoubBas.library will not be loaded by the _main function. The
  217.    whole reason for the Ieee floating point number requirement comes from the
  218.    fact that the code for the DLL can be shared by many applications. There
  219.    are other restrictions as well that arise from this fact.
  220.  
  221.    The C data type 'int' is a 32 bit quantity. The reason that ints are 32
  222.    bits instead of 16 bits is that the 68000 is a 32 bit processor and ints
  223.    are 32 bits in Lattice C. Aztec C has compiler switches that make ints
  224.    32 bits. The DLL really doesn't care what an int is inside your program
  225.    but it does care what the arguments passed to it's functions are. When
  226.    an argument is passed to a CClib function it must be promoted to an int
  227.    before being put on the stack, if it is smaller that an int. In Aztec C
  228.    the easest way to ensure this is to use the +L compiler switch. Another
  229.    way to handle this is to cast 8 and 16 bit arguments to a 32 bit
  230.    quantity.
  231.  
  232.    Another issue that arises from the fact that the DLL code is shared, is
  233.    the problem of re-entrancy. CClib must not modify it's own data in such
  234.    a way it can't be re-used by another application, but some functions in
  235.    any C library implementation must, by nature, use global data. For
  236.    instance the heap memory manager must keep track of a list of free
  237.    memory blocks, and must do so in a way that is transparent to the
  238.    application. It would not due for all of the users of the DLL to share
  239.    the same free memory list. This means that the DLL must allocate a block
  240.    of memory for each of it's users and somehow know which block to use. It
  241.    turns out that there is a very simple way to implement this on the
  242.    Amiga. Every Amiga task must have a Task structure associated with it so
  243.    that Exec can keep track of it. To obtain a pointer to the currently
  244.    running task you call the Exec function FindTask with an argument of
  245.    zero. Also there is an unused member of the Task structure called
  246.    tc_UserData. When the DLL initializes your task it allocates some memory
  247.    from Exec and makes tc_UserData point to that memory. Whenever you call
  248.    a CClib function that requires the use of global data it acceses the
  249.    memory block attached to your task's tc_UserData field. For this reason
  250.    you had better not mess around with your task's tc_UserData member and
  251.    expect CClib to work.
  252.  
  253.    The implementation of file handles and FILE pointers is quite different
  254.    than the implementation in other C libraries. Most C libraries keep a
  255.    static array of FILE structures and a static array of file handles. This
  256.    method is just fine for systems which have a built-in limit as to the
  257.    number of open files a single task can have, but it doesn't make any
  258.    sense for a computer that has no such limitation. For this reason the
  259.    FILE structures and file handles are implemented as linked lists in
  260.    the DLL. This improvement does have one side effect though, there are
  261.    no pre-opened file handles, for example 1 is not the low-level file handle
  262.    for stdio. Instead of hard-coding the low-level file handles you will
  263.    have to use the fileno() macro defined in stdio.h, for example:
  264.    write(fileno(stdin),"Hello World",11L);
  265.  
  266.    Despite these restrictions due to the implementation of the library
  267.    it is hoped that you will find this library useful. Be sure to look at
  268.    the example programs for more information.
  269.  
  270. -------------------------------------------------------------------------
  271.  
  272.    III) FUNCTION DOCUMENTATION
  273.  
  274.    The documentation of the functions in the library follows this format:
  275.  
  276. -------------------------------------------------------------------------
  277. Name:           The name of the C function or macro    [MACRO] =
  278.                               this is a macro
  279.  
  280. Synopsis:      The outline of the function with the type of the argumets
  281.            and the return value.
  282.  
  283. Function:      What actions are taken by this function.
  284.  
  285. Arguments:     An explanation of the arguments to this function.
  286.  
  287. Return:        The return value of the function, and what indicates an
  288.            error condition. It is also indicated if any global variables
  289.            are set by this function.
  290.  
  291. See Also:      Other documentation that will lead to a further understanding
  292.            of the function.
  293. -------------------------------------------------------------------------
  294.  
  295.    1) SUPPORT FUNCTIONS
  296.  
  297.    Some of these functions are not a normal part of a C library but are
  298.    used to support this implementation. Other functions are here because
  299.    they don't fit into another category.
  300.  
  301. -------------------------------------------------------------------------
  302. Name:        abort                 MACRO
  303.  
  304. Synopsis:   #include "stdlib.h"
  305.         void abort()
  306.  
  307. Function:   This is a macro that causes abnormal program termination. It
  308.         is equivalent to exit(EXIT_FAILURE).
  309.  
  310. See Also:   exit
  311. -------------------------------------------------------------------------
  312. Name:        atexit                 MACRO
  313.  
  314. Synopsis:   #include "stdlib.h"
  315.         void atexit( func )
  316.         void (*func)();
  317.  
  318. Function:   Sets the atexit function that is executed when the program
  319.         terminates through a call to exit or _exit. Any existing
  320.         atexit function is over-written. This is defined as a macro
  321.         in stdlib.h.
  322.  
  323. Arguments:  func - a pointer to your atexit function
  324.  
  325. See Also:   exit
  326. -------------------------------------------------------------------------
  327. Name:        ClearAbortFunc
  328.  
  329. Synopsis:   void ClearAbortFunc()
  330.  
  331. Function:   Clears the break signal abort function. A call to this function
  332.         will disable program termination when a ^C or a break is sent
  333.         to it with the AmigaDOS break command.
  334.  
  335. See Also:   SetAbortFunc
  336. -------------------------------------------------------------------------
  337. Name:        ClearSTDIO
  338.  
  339. Synopsis:   void ClearSTDIO()
  340.  
  341. Function:   Returns resources to the system that were used by a process
  342.         using CClib.library. All files are closed and all allocated
  343.         memory is freed. The task's tc_UserData field is re-set to
  344.         it's original condition.
  345.  
  346. See Also:   SetSTDIO, SetupSTDIO
  347. -------------------------------------------------------------------------
  348. Name:        closeall
  349.  
  350. Synopsis:   void closeall()
  351.  
  352. Function:   Closes all opened stream files and low-level files.
  353.  
  354. See Also:   ClearSTDIO
  355. -------------------------------------------------------------------------
  356. Name:        cli_parse
  357.  
  358. Synopsis:   void cli_parse(ud,alen,aptr)
  359.         task_UserData *ud;
  360.         long alen;
  361.         char *aptr;
  362.  
  363. Function:   Parses the command line arguments into argc and argv for
  364.         the main routine. Called only when the program is executed
  365.         from the CLI.
  366.  
  367. Arguments:  ud - a pointer to the task's user data structure.
  368.         alen - the length of the command string passed to the program
  369.         from AmigaDOS.
  370.         aptr - a pointer to the command string passed to the program from
  371.         AmigaDOS.
  372.  
  373. See Also:   wb_parse
  374. -------------------------------------------------------------------------
  375. Name:        exit and _exit()
  376.  
  377. Synopsis:   void exit(code)     void _exit(code)
  378.         long code;        long code;
  379.  
  380. Function:   Causes normal program termination. The atexit() function is
  381.         executed  Open files and streams are closed and flushed, memory
  382.         is de-allocated and returned to the system. Exit may also be
  383.         called when a break signal is received from Amiga DOS.
  384.  
  385. Arguments:  code - the return code of the program. The values EXIT_SUCCESS
  386.         and EXIT_FAILURE may also be used.
  387.  
  388. See Also:   abort, atexit
  389. -------------------------------------------------------------------------
  390. Name:        GetSTDIO
  391.  
  392. Synopsis    task_UserData *GetSTDIO()
  393.  
  394. Function:   Gets a pointer to the block of memory used for global data
  395.         for this task. This function is written in assembly language
  396.         because it is used quite frequently by the library. The
  397.         task_UserData structure is defined in iolib.h.
  398.  
  399. Return:     A pointer to the task's user data block, or NULL if it isn't
  400.         initialized yet.
  401.  
  402. See Also:   SetSTDIO
  403. -------------------------------------------------------------------------
  404. Name:        scdir
  405.  
  406. Synopsis:   char *scdir(pattern)
  407.         char *pattern;
  408.  
  409. Function:   This function is used to support wild card file names using
  410.         '*' and '?' where '*' matches any number of characters and
  411.         '?' matches any single character. To use the function simply
  412.         pass the pattern to the function and keep calling it until
  413.         NULL is returned. For example:
  414.         while( name = scdir("*.c") ) do_something(name);
  415.  
  416. Warning:    This function allocates memory from the system that is not
  417.         freed until it returns NULL. So that the memory gets returned
  418.         to the system be sure keep calling it until NULL is returned,
  419.         if you don't the memory will remain allocated until the program
  420.         exits. Also the file pattern is irrelavent after the first call
  421.         to scdir because it remembers the pattern in it's own memory.
  422.         The memory used by scdir is pointed to by
  423.         task_UserData.scdir_mem and if you wish to scan another directory
  424.         before the current one is finished you can save this pointer,
  425.         set it to NULL, scan the other directory, restore the pointer
  426.         and then keep calling scdir until NULL is returned.
  427.  
  428. Arguments:  pattern - the file name pattern.
  429.  
  430. Return:     A pointer to a file name that matches the pattern or NULL.
  431. -------------------------------------------------------------------------
  432. Name:        SetAbortFunc
  433.  
  434. Synopsis:   void SetAbortFunc(func)
  435.         long (*func)();
  436.  
  437. Function:   Sets the break signal abort function. Whenever a break signal
  438.         is detected from AmigaDOS, sent either by a ^C from the console
  439.         or from an AmigaDOS break command, the library will see if there
  440.         is an abort function, and if there is it will be executed with
  441.         the signals that caused it to be executed as an argument. The
  442.         signals will be in a 32 bit integer. During normal operation
  443.         the function _exit is the abort function, however you may wish
  444.         to set it to something else so that you can clean up whatever
  445.         your application is doing at the time. If you intend to exit
  446.         from the program call the exit or _exit functions, not the
  447.         AmigaDOS Exit function,  or else resources allocated by
  448.         the library will not be de-allocated.
  449.  
  450. Arguments:  func - a pointer to the abort function to be used when a
  451.         break signal is received.
  452.  
  453. See Also:   ClearAbortFunc
  454. -------------------------------------------------------------------------
  455. Name:        SetSTDIO
  456.  
  457. Synopsis:   long SetSTDIO()
  458.  
  459. Function:   Allocates memory for a task_UserData structure and attaches
  460.         it to the tc_UserData field of the task structure.
  461.  
  462. Return:     Zero is returned if the operation was a success, otherwise
  463.         one is returned.
  464.  
  465. See Also:   SetupSTDIO
  466. -------------------------------------------------------------------------
  467. Name:        SetupSTDIO
  468.  
  469. Synopsis:   long SetupSTDIO(ud,in,out,err,errno,bsize,ctyp,mathbase)
  470.         FILE **in, **out, **err;
  471.         long *errno, *bsize;
  472.         char **ctyp;
  473.         void *mathbase;
  474.         long alen;
  475.         char *aptr;
  476.         struct WBStartup *wbm;
  477.         void (*_xit)();
  478.  
  479. Function:   Gives the library access to global variables that reside in the
  480.         application program and opens standard input, output and error
  481.         streams and allocates the SetSTDIO to allocate the memory that
  482.         is pointed to by task->tc_UserData. Standard I/O will not be
  483.         opened for programs run from the workbench that have no
  484.         "WINDOW" tooltype in their tool icon, or for programs run
  485.         from the workbench by projects.
  486.  
  487. Arguments:  in, out, err - memory locations where pointers to the standard
  488.         stream files are stored in the application program.
  489.         errno - the memory location where the global variable errno
  490.         is stored.
  491.         bsize - the memory location where the global variable blocksize
  492.         is stored. blocksize is used by the heap manager to determine the
  493.         minimum size of the memory blocks to be allocated from AmigaDOS.
  494.         ctyp - this is the 'type' array that is used by the macros in
  495.         ctype.h. The array is actually in the library and the
  496.         application just gets a pointer to it.
  497.         mathbase - The address of the MathIeeDoubBas library base pointer
  498.         to be used for programs that use floating point numbers.
  499.         alen - the length of the command line passed to the program by
  500.         the CLI process, if run from the CLI.
  501.         aptr - a pointer to the command line passed to the program by the
  502.         CLI process, if run form the CLI.
  503.         wbm - a pointer to the workbench startup message sent by the
  504.         workbench program. This will be used by wb_parse to open a
  505.         standard I/O window for the application if the Tooltype
  506.         "WINDOW" is set.
  507.         _xit - a pointer to the applications exit routine. This is set
  508.         to be exit() by the _main routine.
  509.  
  510. Return:     One is returned if all of the initialization was successful,
  511.         otherwise zero is returned.
  512. -------------------------------------------------------------------------
  513. Name:        system                 MACRO
  514.  
  515. Synopsis:   #include "stdlib.h"
  516.         system(command)
  517.         char *command;
  518.  
  519. Function:   Executes a command as if it was typed in on the CLI command
  520.         line. The RUN command must be in the path or in the C: directory
  521.         for this function to work.
  522.  
  523. Arguments:  command - The command to execute, for example:
  524.         system("FORMAT DRIVE DH0: NAME TRASHED") will format
  525.         your hard drive immediatly without asking.
  526.  
  527. Return:     Zero is returned on failure.
  528. -------------------------------------------------------------------------
  529. Name:        wb_parse
  530.  
  531.         long wb_parse(ud, wbmsg)
  532.         task_UserData *ud;
  533.         struct WBStartup **wbmsg;
  534.  
  535. Function:   Checks the Tool Types of the icon associated with this program.
  536.         If the Tool Type WINDOW is found a window is opened using the
  537.         Tool Type's value. This window is used for standard input and
  538.         output. If the WINDOW tool type is not found then a program
  539.         run from the workbench will have NO standard input, output, and
  540.         error, and any attempt to write to these non-existant devices
  541.         will almost certainly cause a system crash. A good example of
  542.         a valid tool type would be:
  543.         WINDOW=CON:20/10/300/100/WindowTitle
  544.  
  545. Arguments:  ud - a pointer to the task's task_UserData structure.
  546.         wbmsg - a pointer to the workbench startup message for this
  547.         program.
  548.  
  549. Return:     Non-zero is returned if a window was opened for standard
  550.         input and output.
  551.  
  552. See Also:   cli_parse
  553. -------------------------------------------------------------------------
  554.  
  555.    2) STREAM I/O FUNCTIONS
  556.  
  557.    These functions send and receive bytes from "streams". A stream is the
  558.    data type FILE that is defined in stdio.h. Some of the functions
  559.    are implemented as macros that are defined in stdio.h. Other functions
  560.    read and write to the standard pre-opened stream files "stdin", "stdout"
  561.    and "stderr". When an error occurs with one of these functions the
  562.    global variable errno will contain further information.
  563.  
  564. -------------------------------------------------------------------------
  565. Name:        agetc
  566.  
  567. Synopsis:   short agetc(fp)
  568.         FILE *fp;
  569.  
  570. Function:   Gets one character from the designated stream. This function
  571.         is here to support existing implementations of the C library
  572.         and should not be used in new code.
  573.  
  574. Arguments:  fp - a pointer to the stream file to receive input from.
  575.  
  576. Return:     The character received as input, of EOF if the end of the
  577.         file has been reached, or if an error has occured.
  578.  
  579. See Also:   getc
  580. -------------------------------------------------------------------------
  581. Name:        aputc
  582.  
  583. Synopsis:   short aputc(c,fp)
  584.         short c;
  585.         FILE *fp;
  586.  
  587. Function:   Writes one character to the specified stream. This function is
  588.         here to support existing implementations of the C library and
  589.         should not be used in new code.
  590.  
  591. Arguments:  c - the character to write
  592.         fp - the stream to write to.
  593.  
  594. Return:     EOF is returned on error.
  595.  
  596. See Also:   putc
  597. -------------------------------------------------------------------------
  598. Name:        clearerr                 MACRO
  599.  
  600. Synopsis:   #include "stdio.h"
  601.         int clearerr(fp)
  602.         FILE *fp;
  603.  
  604. Function:   Clears end of file and error indicators in a stream.
  605.  
  606. Arguments:  fp - pointer to a stream file
  607.  
  608. See Also:   feof, ferror
  609. -------------------------------------------------------------------------
  610. Name:        fclose
  611.  
  612. Synopsis:   long fclose(fp)
  613.         FILE *fp;
  614.  
  615. Function:   Closes a stream file.
  616.  
  617. Arguments:  fp - stream file to close
  618.  
  619. Return:     Zero is returned if the operation was successful, otherwise
  620.         non-zero is returned.
  621.  
  622. See Also:   fopen
  623. -------------------------------------------------------------------------
  624. Name:        fdopen
  625.  
  626. Synopsis:   FILE *fdopen(fh,fmode)
  627.         long fh;
  628.         char *fmode;
  629.  
  630. Function:   Creates a stream file from a low-level file handle.
  631.         This function is here to support existing C library
  632.         implementations and should not be used in new code.
  633.  
  634. Arguments:  fh - the low-level file handle
  635.         fmode - not used in this implementation, but used to contain the
  636.         file open modes.
  637.  
  638. Return:     A pointer to the new stream file is returned, otherwise NULL.
  639.  
  640. See Also:   fopen
  641. -------------------------------------------------------------------------
  642. Name:        feof                 MACRO
  643.  
  644. Synopsis:   #include "stdio.h"
  645.         int feof(fp)
  646.         FILE *fp;
  647.  
  648. Function:   Tests for end of file.
  649.  
  650. Arguments:  fp - pointer to a stream file
  651.  
  652. Return:     Retuns non-zero if the end of file bit is set in the stream.
  653. -------------------------------------------------------------------------
  654. Name:        ferror                 MACRO
  655.  
  656. Synopsis:   #include "stdio.h"
  657.         int ferror(fp)
  658.         FILE *fp;
  659.  
  660. Function:   Tests for file error.
  661.  
  662. Arguments:  fp - pointer to a stream file
  663.  
  664. Return:     Returns non-zero if the error bit is set in the stream.
  665. -------------------------------------------------------------------------
  666. Name:        fflush
  667.  
  668. Synopsis:   long fflush(fp)
  669.         FILE *fp;
  670.  
  671. Function:   Causes buffered but unwritten data to be written on an output
  672.         file. The operation is undefined for input streams.
  673.  
  674. Arguments:  fp - the stream file to flush
  675.  
  676. Return:     EOF is returned on a write error, otherwise zero is returned.
  677. -------------------------------------------------------------------------
  678. Name:        fgetc                 MACRO
  679.  
  680. Synopsis:   #include "stdio.h"
  681.         int fgetc(fp)
  682.         FILE *fp;
  683.  
  684. Function:   Gets one character from the designated stream.
  685.  
  686. Arguments:  fp - a pointer to the stream file to receive input from.
  687.  
  688. Return:     The character received as input, of EOF if the end of the
  689.         file has been reached, or if an error has occured.
  690.  
  691. See Also:   getc
  692.  
  693. -------------------------------------------------------------------------
  694. Name:        fgetpos
  695.  
  696. Synopsis:   #inlude "stdio.h"
  697.         long fgetpos(fp,pos)
  698.         FILE *fp;
  699.         fpos_t *pos;
  700.  
  701. Function:   Saves the current position in a stream file into a variable
  702.         that is suitable for a call to fsetpos.
  703.  
  704. Arguments:  fp - stream to get the current position of
  705.         pos - current position is saved to this address. The data
  706.         type fpos_t is defined in stdio.h.
  707.  
  708. Return:     Non-zero is returned on an error.
  709.  
  710. See Also:   fsetpos
  711. -------------------------------------------------------------------------
  712. Name:        fgets
  713.  
  714. Synopsis:   char *fgets(buf,n,fp)
  715.         char *buf;
  716.         long n;
  717.         FILE *fp;
  718.  
  719. Function:   Reads at most n-1 bytes from a stream file into an array,
  720.         if a '\n' character is encountered it is included
  721.         in the array which is then NULL terminated.
  722.  
  723. Arguments:  buf - pointer to the array of bytes to store the input.
  724.         n - maximum number of bytes to read.
  725.         fp - pointer to the stream file to read from.
  726.  
  727. Return:     buf is returned unless the end of file is reached or an error
  728.         occurs in which case NULL is returned.
  729.  
  730. See Also:   fputs
  731. -------------------------------------------------------------------------
  732. Name:        fopen
  733.  
  734. Synopsis:   FILE *fopen(fname,fmode)
  735.         char *fname;
  736.         char *fmode;
  737.  
  738. Function:   Opens a sream file.
  739.  
  740. Arguments:  fname - the name of the file to open. The file name may be up
  741.         to FILENAME_MAX characters long.
  742.         fmode - the mode to open the file in. Legal values include:
  743.         "r"   open a file for reading
  744.         "w"   create a file for writing, discard contents if any.
  745.         "a"   append; open or create a file for writing at the end.
  746.         "r+"  open a file for update, reading and writing)
  747.         "w+"  create a file for update, discard previous contents
  748.         "a+"  append; open or create a file for update, write at end
  749.         Optionally a 'b' may be added to the open mode, but this is not
  750.         needed for the Amiga system because there is no distinction
  751.         between text files and binary files.
  752.  
  753. Return:     A pointer to a stream file is returned, if an error occurs NULL
  754.         is returned.
  755.  
  756. See Also:   fclose
  757. -------------------------------------------------------------------------
  758. Name:        fprintf
  759.  
  760. Synopsis:   long fprintf(fp,fmt,...)
  761.         FILE *fp;
  762.         char *fmt;
  763.  
  764. Function:   Sends formatted output to a stream file. For a more detailed
  765.         description of formatted output please see printf.
  766.  
  767. Arguments:  fp - pointer to the stream file
  768.         fmt - format to print the arguments with.
  769.         ... - a variable number of arguments that is specified in fmt.
  770.  
  771.  
  772. Return:     The number of characters written is returned.
  773.  
  774. See Also:   printf
  775. -------------------------------------------------------------------------
  776. Name:        fputc                 MACRO
  777.  
  778. Synopsis:   #include "stdio.h"
  779.         int fputc(c,fp)
  780.         short c;
  781.         FILE *fp;
  782.  
  783. Function:   Writes one character to the specified stream.
  784.  
  785. Arguments:  c - character to write
  786.         fp - stream to write to
  787.  
  788. Return:     EOF is returned on error
  789.  
  790. See Also:   putc
  791. -------------------------------------------------------------------------
  792. Name:        fputs
  793.  
  794. Synopsis:   long fputs(string,fp)
  795.         char *string;
  796.         FILE *fp;
  797.  
  798. Function:   Sends a string to the specified stream file.
  799.  
  800. Arguments:  string - NULL terminated string to send.
  801.         fp - stream to send the string to.
  802.  
  803. Return:     EOF is returned on error, otherwise > 0.
  804.  
  805. See Also:   fgets
  806. -------------------------------------------------------------------------
  807. Name:        fread
  808.  
  809. Synopsis:   #include "stdio.h"
  810.         size_t fread(buf,size,nobj,fp)
  811.         void *buf;
  812.         size_t size;
  813.         size_t nobj;
  814.         FILE *fp;
  815.  
  816. Function:   Reads from a stream into an array at most nobj elements of
  817.         size. (number of bytes = size*nobj).
  818.  
  819. Arguments:  buf - buffer to store the data
  820.         size - size of each element to read
  821.         nobj - number of elements to read
  822.         fp - stream to read from
  823.  
  824. Return:     The number of elements read, which may be less than nobj due
  825.         to an end of file or error condition.
  826.  
  827. See Also:   fwrite
  828. -------------------------------------------------------------------------
  829. Name:        freopen
  830.  
  831. Synopsis:   FILE *freopen(fname, fmode, oldfp)
  832.         char *fname;
  833.         char *fmode;
  834.         FILE *oldfp;
  835.  
  836. Function:   Re-opens a stream file with a different name and possibly a
  837.         different file mode. It is most commonly used to re-direct
  838.         stdin, stdout, and stderr.
  839.  
  840. Arguments:  fname - name of the stream to open
  841.         fmode - mode to open the stream in. See the description of
  842.         fopen for the legal file modes.
  843.         oldfp - the stream to re-open.
  844.  
  845. Return:     A pointer to the new stream is returned if the operation was
  846.         successful, otherwise NULL is returned.
  847.  
  848. See Also:   fopen
  849. -------------------------------------------------------------------------
  850. Name:        fscanf
  851.  
  852. Synopsis:   long fscanf(fp,fmt,...);
  853.         FILE *fp;
  854.         char *fmt;
  855.  
  856. Function:   Reads formatted input from a stream. For a further explanation
  857.         of formatted input please see scanf.
  858.  
  859. Arguments:  fp - stream to read the formatted input from.
  860.         fmt - format of the arguments to be read.
  861.         ... - a variable number of arguments that are specified in fmt.
  862.         Each of the arguments to fscanf must be a pointer.
  863.  
  864. Return:     The number of items converted and assigned is returned.
  865.  
  866. See Also:   scanf
  867. -------------------------------------------------------------------------
  868. Name:        fseek
  869.  
  870. Synopsis:   #include "stdio.h"
  871.         long fseek(fp,offset,origin)
  872.         FILE *fp;
  873.         long offset;
  874.         long origin;
  875.  
  876. Function:   Sets the position in a stream relative to "origin".
  877.  
  878. Arguments:  fp - stream to set the position of.
  879.         offset - offset in bytes to set the position to.
  880.         origin - position realtive to which the new position will
  881.         be set. The values for origin may be SEEK_SET (beginning),
  882.         SEEK_CUR, (current position), SEEK_END (end of file).
  883.  
  884. Return:     Non-zero is returned when an error occurs.
  885.  
  886. See Also:   ftell, fsetpos
  887. -------------------------------------------------------------------------
  888. Name:        fsetpos
  889.  
  890. Synopsis:   long fsetpos(fp,pos)
  891.         FILE *fp;
  892.         fpos_t *pos;
  893.  
  894. Function:   Positions a stream to a position saved by fgetpos.
  895.  
  896. Arguments:  fp - stream to set the position of.
  897.         pos - pointer to the position saved by fgetpos.
  898.  
  899. Return:     Non-zero is returned when an error occurs.
  900.  
  901. See Also:   fseek
  902. -------------------------------------------------------------------------
  903. Name:        ftell
  904.  
  905. Synopsis:   long ftell(fp)
  906.         FILE *fp;
  907.  
  908. Arguments:  fp - a stream file.
  909.  
  910. Return:     Returns the current file position, of -1 if an error occurs.
  911.  
  912. See Also:   fgetpos
  913. -------------------------------------------------------------------------
  914. Name:       fwrite
  915.  
  916. Synopsis:   #include "stdio.h"
  917.         size_t fwrite(buf,size,nobj,fp)
  918.         void *buf;
  919.         size_t size, nobj;
  920.         FILE *fp;
  921.  
  922. Function:   Writes from an array to a stream, at most nobj elements of size
  923.         size are written.
  924.  
  925. Arguments:  buf -  array to write from.
  926.         size - size of the elements to write.
  927.         nobj - number of elements to write.
  928.         fp - stream to write to.
  929.  
  930. Return:     The number of element written is returned, which is less than
  931.         nobj on error.
  932.  
  933. See Also:   fread
  934. -------------------------------------------------------------------------
  935. Name:        getbuff
  936.  
  937. Synopsis:   void getbuff(fp)
  938.         FILE *fp;
  939.  
  940. Function:   Allocates the standard sized buffer for buffered input and
  941.         output. The function must be called before any reading or
  942.         writing is done. It will be called for you otherwise.
  943.  
  944. Arguments:  fp - stream to attach the buffer to.
  945.  
  946. See Also:   setvbuf
  947. -------------------------------------------------------------------------
  948. Name:        getc
  949.  
  950. Synopsis:   short getc(fp)
  951.         FILE *fp;
  952.  
  953. Function:   Gets one character from the designated stream.
  954.  
  955. Arguments:  stream - a pointer to the stream file to receive input from.
  956.  
  957. Return:     The character received as input, of EOF if the end of the
  958.         file has been reached, or if an error has occured.
  959.  
  960. See Also:   fgetc
  961. -------------------------------------------------------------------------
  962. Name:        getchar                 MACRO
  963.  
  964. Synopsis:   #include "stdio.h"
  965.         short getchar();
  966.  
  967. Function:   Reads one character from the standard input.
  968.  
  969. Return:     The character received as input, of EOF if the end of the
  970.         file has been reached, or if an error has occured.
  971.  
  972. See Also:   getc
  973. -------------------------------------------------------------------------
  974. Name:        getchar
  975.  
  976. Synopsis:   #define NOMACROS
  977.         #include stdio.h     or     short getchar();
  978.         short getchar();
  979.  
  980. Function:   Reads one character from the standard input.
  981.  
  982. Return:     The character received as input, of EOF if the end of the
  983.         file has been reached, or if an error has occured.
  984.  
  985. See Also:   getc
  986. -------------------------------------------------------------------------
  987. Name:        gets
  988.  
  989. Synopsis:   char *gets(buf)
  990.         char *buf;
  991.  
  992. Function:   Reads a line from the standard input. The newline '\n' is
  993.         replaced by a '\0'.
  994.  
  995. Arguments:  buf - array of characters where the input line is stored.
  996.  
  997. Return:     Returns buf unless end of file or an error occurs in which
  998.         case NULL is returned.
  999.  
  1000. See Also:   puts,fputs
  1001. -------------------------------------------------------------------------
  1002. Name:        getw
  1003.  
  1004. Synopsis:   short getw(fp)
  1005.         FILE *fp;
  1006.  
  1007. Function:   Reads a 16 bit word from the specified stream.
  1008.  
  1009. Arguments:  fp - stream to read the word from.
  1010.  
  1011. Return:     EOF is returned on error, otherwise the data read from the
  1012.         stream is returned.
  1013.  
  1014. See Also:   putw
  1015. -------------------------------------------------------------------------
  1016. Name:        mktemp
  1017.  
  1018. Synopsis:   char *mktemp(buf)
  1019.  
  1020. Function:   Creates a temporary file name from a template whose last few
  1021.         characters are 'X'. For example "BOBXXXX.XX".
  1022.  
  1023. Arguments:  buf - template to create the file name from.
  1024.  
  1025. Return:     buf is returned.
  1026.  
  1027. See Also:   tmpnam
  1028. -------------------------------------------------------------------------
  1029. Name:        perror
  1030.  
  1031. Synopsis:   long perror(msg)
  1032.         char *msg;
  1033.  
  1034. Function:   Prints an error message corresponding to the number in errno
  1035.         along with a message you provide to stderr.
  1036.  
  1037. Arguments:  msg - supplimental error message, or NULL if you don't have one.
  1038.  
  1039. Return:     Zero is returned on success, -1 is returned if the error number
  1040.         in errno has no corresponding error message or if an error
  1041.         error occurs with the execution of perror.
  1042.  
  1043. See Also:   puterr
  1044. -------------------------------------------------------------------------
  1045. Name:        printf
  1046.  
  1047. Synopsis:   long printf(fmt,...)
  1048.         char *fmt;
  1049.  
  1050. Function:   Writes formatted output to stdout under control of a
  1051.         format string.
  1052.  
  1053. Arguments:  fmt - format of the following arguments.
  1054.         fmt contains two things, regular characters which are copied
  1055.         to stdout, and conversion specifications, each of which causes
  1056.         conversion and printing of the next argument in the variable
  1057.         argument list. Every conversion specification begins with a
  1058.         '%' character and ends with a converson character. Before the
  1059.         conversion character there may be one or more modifiers. Below
  1060.         is a list of the modifiers in the order that they must appear.
  1061.  
  1062.         1) Flags (in any order) [-+0 ]
  1063.            '-'   specifies left justification within the field
  1064.            '+'   specifies that the number will be printed with a sign
  1065.            ' '   space is printed if the first character isn't a sign
  1066.            '0'   for numeric conversions leading zeros will be printed
  1067.              instead of spaces
  1068.            '#'   is NOT supported yet
  1069.         2) Field Width [0123456789]
  1070.            The minimum field width that the converted argument will
  1071.            be printed in. The argument may be printed in a wider field
  1072.            if it would overflow the field. If the converted argument
  1073.            has fewer characters it will be padded with spaces, unless
  1074.            zeros are specified.
  1075.         3) A period, [.]
  1076.            seperating the field width from the precision.
  1077.         4) Precision number [0123456789]
  1078.            o  For character strings; specifies the maximum number of
  1079.           characters to be printed.
  1080.            o  For floating point numbers in e, E, or f formats the number
  1081.           of digits to be printed after the decimal point.
  1082.            o  For floating point numbers in the G or g formats the number
  1083.           of significant digits to be printed.
  1084.            o  For integral numbers the minimum number of digits to be
  1085.           printed, leading zeros will be added if the number isn't
  1086.           big enough to be prited.
  1087.         5) Argument length specifier [lh]
  1088.            If the length specifier is not present then the argument
  1089.            is taken to be the short ('h') form.
  1090.           For integral values:
  1091.            The length specifier is completly optional for integral values
  1092.            because all 16 bit arguments must be promoted to a 32 bit
  1093.            quantity before passing them to a CClib.library function.
  1094.            o  'l' prints the argument as long or unsigned long.
  1095.            o  'h' prints the argument as short or unsigned short.
  1096.           For floating point values:
  1097.            o  'h' prints the argument as a float.
  1098.            o  'l' prints the argument as a double.
  1099.            o  'L' is NOT supported due to the lack of the long double
  1100.           data type on the Amiga.
  1101.  
  1102.              Printf conversion characters.
  1103.  
  1104.            d, i    signed decimal number
  1105.            o    unsigned octal number
  1106.            x, X    unsigned hexadecimal number using lowercase letters
  1107.             for 'x' and upper case letters for 'X'
  1108.            u    unsigned decimal number
  1109.            c    a single character
  1110.            s    a NULL terminated string
  1111.            f    float or double depending on the length specifier to
  1112.             be printed with a fixed decimal point
  1113.            e, E    float or double depending on the length specifier to
  1114.             be printed in exponential notation
  1115.            g, G    float or double depending on the length specifier to
  1116.             be printed with whatever is shorter, 'e' of 'f'
  1117.             format
  1118.            p    print as a pointer (this is really the same as
  1119.             'x' format on the Amiga).
  1120.            n    this is NOT supported yet, but should put the
  1121.             number of characters printed so far into the
  1122.             argument.
  1123.            %    prints the '%' character
  1124.  
  1125. Return:        The number of characters printed is returned or negative
  1126.            if an error occurs.
  1127.  
  1128. See Also:      fprintf, vprintf, vfprintf
  1129. -------------------------------------------------------------------------
  1130. Name:        putc
  1131.  
  1132. Synopsis:   short putc(c,fp)
  1133.         short c;
  1134.         FILE *fp;
  1135.  
  1136. Function:   Writes one byte to the specified stream.
  1137.  
  1138. Arguments:  c - character to write
  1139.         fp - stream to write to
  1140.  
  1141. Return:     EOF is returned on error
  1142.  
  1143. See Also:   getc
  1144. -------------------------------------------------------------------------
  1145. Name:        putchar                 MACRO
  1146.  
  1147. Synopsis:   #include "stdio.h"
  1148.         short putchar(c)
  1149.         short c;
  1150.  
  1151. Function:   Writes one character to the standard output.
  1152.  
  1153. Arguments:  c - the character to write
  1154.  
  1155. Return:     EOF is returned on error.
  1156.  
  1157. See Also:   putc
  1158. -------------------------------------------------------------------------
  1159. Name:        putchar
  1160.  
  1161. Synopsis:   #defile NOMACROS 1
  1162.         #include "stdio.h"         or    short putchar(c)
  1163.         short putchar(c)                 short c;
  1164.         short c;
  1165.  
  1166. Function:   Writes one character to the standard output.
  1167.  
  1168. Arguments:  c - the character to write
  1169.  
  1170. Return:     EOF is returned on error.
  1171.  
  1172. See Also:   putc
  1173. -------------------------------------------------------------------------
  1174. Name:        puterr
  1175.  
  1176. Synopsis:   short puterr(c)
  1177.         short c;
  1178.  
  1179. Function:   Writes one character to stderr.
  1180.  
  1181. Arguments:  c - character to write
  1182.  
  1183. Return:     EOF is returned on error
  1184.  
  1185. See Also:   perror
  1186. -------------------------------------------------------------------------
  1187. Name:        puts
  1188.  
  1189. Synopsis:   short puts(str)
  1190.         char *str;
  1191.  
  1192. Function:   Writes a NULL terminated string and a newline ('\n') character
  1193.         to stdout.
  1194.  
  1195. Arguments:  str - string to write
  1196.  
  1197. Return:     EOF is returned on error
  1198.  
  1199. See Also:   gets
  1200. -------------------------------------------------------------------------
  1201. Name:        putw
  1202.  
  1203. Synopsis:   unsigned short putw(w,fp)
  1204.         unsigned short w;
  1205.         FILE *fp;
  1206.  
  1207. Function:   Writes a 16 bit word to the specified stream.
  1208.  
  1209. Arguments:  w - word to write
  1210.         fp - stream to write to
  1211.  
  1212. Return:     w is returned when no error occurs, otherwise EOF.
  1213.  
  1214. See Also:   putc
  1215. -------------------------------------------------------------------------
  1216. Name:        remove                 MACRO
  1217.  
  1218. Synopsis:   #include "stdio.h"
  1219.         long remove(fname)
  1220.         char *fname;
  1221.  
  1222. Function:   Deletes a file.
  1223.  
  1224. Arguments:  fname - name of the file to delete
  1225.  
  1226. Return:     Non-zero is returned on error.
  1227.  
  1228. See Also:   unlink
  1229. -------------------------------------------------------------------------
  1230. Name:        rename
  1231.  
  1232. Synopsis:   long rename(oldfname,newfname)
  1233.         char *oldfname;
  1234.         char *newfname;
  1235.  
  1236. Function:   Renames a file. In AmigaDOS files may be renamed across
  1237.         directories but not across volumes. For example
  1238.         rename("RAM:t/junk","RAM:t/stuff/junk); would be legal but
  1239.         rename("RAM:t/junk","DF0:junk"); would not be.
  1240.  
  1241. Arguments:  oldfname - name of the file to rename
  1242.         newfname - new name of the file
  1243.  
  1244. Return:     Non-zero is returned on error.
  1245. -------------------------------------------------------------------------
  1246. Name:        rewind                 MACRO
  1247.  
  1248. Synopsis:   #include "stdio.h"
  1249.         void rewind(fp)
  1250.         FILE *fp;
  1251.  
  1252. Function:   Sets the position of a stream file to the beginning of the file.
  1253.  
  1254. Arguments:  fp - stream file pointer
  1255.  
  1256. See Also:   fseek
  1257. -------------------------------------------------------------------------
  1258. Name:        scanf
  1259.  
  1260. Synopsis:   long scanf(fmt,...)
  1261.         char *fmt;
  1262.  
  1263. Function:   Reads formatted input from stdin under control of a format
  1264.         string.
  1265.  
  1266. Arguments:  fmt - format conversion string. The format sring is used to
  1267.         direct the interpretation of input. The format string may
  1268.         contain;
  1269.         1) whitespace (blanks and tabs) which is ignored.
  1270.         2) Characters other that % which are expected to match
  1271.            the next non-whitespace character of input.
  1272.         3) All conversion specifications are preceeded with a '%'
  1273.            character.
  1274.         4) Field Width [0123456789]
  1275.            Specifies the maimum width of a field.
  1276.         5) Argument length specifier [lh]
  1277.            The argument length specifier determines the size of the
  1278.            variable pointed to by the corresponding argument.
  1279.            If the length specifier is not present then the argument
  1280.            is taken to be the short ('h') form.
  1281.           For integral values:
  1282.            o  'l' converts the input as long or unsigned long.
  1283.            o  'h' converts the input as short or unsigned short.
  1284.           For floating point values:
  1285.            o  'h' converts the argument as a float.
  1286.            o  'l' converts the argument as a double.
  1287.            o  'L' is NOT supported due to the lack of the long double
  1288.           data type on the Amiga.
  1289.         6) Conversion specifications. Each conversion specification
  1290.            determines the conversion of the next field of input. Unless
  1291.            the suppression character '*' is used the input is stored in
  1292.            the next variable corresponding to the next argument. For
  1293.            each variable conversion continues until a whitespace
  1294.            character is encountered, or until the number of characters
  1295.            specified in the maximum field width of the conversion specification
  1296.            are encountered.
  1297.  
  1298.                 Scanf conversion characters.
  1299.  
  1300.            d, i    signed decimal number
  1301.            o    unsigned octal number
  1302.            x    unsigned hexadecimal number
  1303.            u    unsigned decimal number
  1304.            c    input characters are placed in the indicated array
  1305.             up to the number specified in the field width; the
  1306.             default is 1, No '\0' os added. %c will convert the
  1307.             next character INCLUDING whitespace. To read the
  1308.             next non-whitespace character use %1s.
  1309.            s    a NULL terminated string
  1310.            e,f,g    float or double depending on the length specifier
  1311.            p    pointer (this is really the same as 'x' format
  1312.             on the Amiga).
  1313.            n    this is NOT supported yet, but should put the
  1314.             number of characters read so far into the
  1315.             argument.
  1316.            [...]    Null terminated string. Matches the longest
  1317.             non-empty string of input characters from the set
  1318.             of characters between brackets. The string is NULL
  1319.             terminated. []...] includes ']' in the set.
  1320.            [^...]    Null terminated string. Matches the longest
  1321.             non-empty string of input characters NOT from the
  1322.             set of characters between the brackets. The string
  1323.             in NULL terminated. [^]...] excludes ']' from the
  1324.             set.
  1325.            %    the '%' character, no assignment is made
  1326.  
  1327.  
  1328.         ...   - a variable number of arguments each of which is a pointer
  1329.           to a variable whose type is determined by the contents of
  1330.           the format string.
  1331.  
  1332.  
  1333. Return:     The number of items converted and assigned (stored) is
  1334.         returned. If an error occurs or if end of file is reached
  1335.         EOF is returned.
  1336.  
  1337. See Also:   fscanf, sscanf, printf
  1338. -------------------------------------------------------------------------
  1339. Name:        setbuf                 MACRO
  1340.  
  1341. Synopsis:   #include "stdio.h"
  1342.         void setbuf(fp,buf)
  1343.         FILE *fp;
  1344.         char *buf;
  1345.  
  1346. Function:   If buf is NULL buffering for this stream is eliminated,
  1347.         otherwise setbuf is the same as setvbuf(fp,buf,_IOFBF,BUFSIZ).
  1348.  
  1349. Arguments:  fp - stream file pointer
  1350.         buf - buffer to set
  1351.  
  1352. See Also:   setvbuf
  1353. -------------------------------------------------------------------------
  1354. Name:        setvbuf
  1355.  
  1356. Synopsis:   #include "stdio.h"
  1357.         long setvbuf(fp,buf,mode,size)
  1358.         FILE *fp;
  1359.         char *buf;
  1360.         long mode;
  1361.         size_t size;
  1362.  
  1363. Function:   Controls buffering for a stream by attaching an application
  1364.         specific buffer to the stream. If setvbuf is to be used then
  1365.         it must be called before any reading or writing is done on the
  1366.         stream.
  1367.  
  1368. Arguments:  fp - stream to add the buffer to
  1369.         buf - buffer to be used, if the buf argument is NULL then a
  1370.         buffer will be allocated for the stream using malloc that is the
  1371.         size specified by the size argument.
  1372.         mode - the mode of buffering, _IOFBF causes full buffering,
  1373.         _IOLBF should cause the buffering of text lines but is the same
  1374.         as _IOFBF for this implementation, _IONBF causes no buffering.
  1375.         size - size of the buffer provided or to be allocated.
  1376.  
  1377. Return:     Non-zero is returned for any error.
  1378.  
  1379. See Also:   setbuf
  1380. -------------------------------------------------------------------------
  1381. Name:        sprintf
  1382.  
  1383. Synopsis:   long sprintf(buf,fmt,...)
  1384.         char *buf;
  1385.         char *fmt;
  1386.  
  1387. Function:   Prints formatted output to a NULL terminated string under control
  1388.         of a format string.
  1389.  
  1390. Arguments:  buf - buffer to write the output to
  1391.         fmt - format string, see the documentation for the printf
  1392.         function for a description of the format string.
  1393.         ... - variable number of arguments under control of the
  1394.         format string.
  1395.  
  1396. Return:     The number of characters printed not including the NULL
  1397.         terminator.
  1398.  
  1399. See Also:   printf
  1400. -------------------------------------------------------------------------
  1401. Name:        sscanf
  1402.  
  1403. Synopsis:   long sscanf(str,fmt,...)
  1404.         char *str, *fmt;
  1405.  
  1406. Function:   Identical to scanf except that input characters are taken
  1407.         from the string str instead of stdin.
  1408.  
  1409. Arguments:  str - string to take input from
  1410.         fmt - format string, see documentation for the scanf function
  1411.         ... - variable number of arguments each of which is a pointer
  1412.  
  1413. Return:        The number of items converted and assigned (stored) is
  1414.            returned.
  1415.  
  1416. See Also:   scanf
  1417. -------------------------------------------------------------------------
  1418. Name:        stat
  1419.  
  1420. Synopsis:   #include "stat.h"
  1421.         long stat(fname,stat)
  1422.         char *fname;
  1423.         struct stat *stat;
  1424.  
  1425. Function:   Retrieves information about a file.
  1426.  
  1427. Arguments:  fname - name of the file to get the information about
  1428.         stat - structure to hold the results. The stat structure
  1429.         is described below;
  1430.  
  1431.         struct stat
  1432.         {
  1433.         unsigned short st_attr;
  1434.         long st_mtime;
  1435.         long st_size;
  1436.         };
  1437.  
  1438.         st_attr - file attributes which may be or'd together including:
  1439.           This Bit On       Means
  1440.            ST_DELETE   -  file is NOT deletable
  1441.            ST_EXECUTE  -  file is NOT executable
  1442.            ST_WRITE    -  file is NOT writeable
  1443.            ST_READ       -  file is NOT readable
  1444.            ST_ARCHIVE  -  file HAS been archived
  1445.         A warning about attribute bits; It is unsafe to assume that
  1446.         the other bits available in the attribute field will be un-used.
  1447.         This is because they may be used in future implementations of
  1448.         the Amiga operating system. This has already happened in the
  1449.         case of the ST_ARCHIVE bit.
  1450.  
  1451.         st_mtime - File modification date, in seconds since Jan, 1 1978
  1452.  
  1453.         st_size - of file in bytes
  1454.  
  1455. Return:     Non-zero is returned on error.
  1456. -------------------------------------------------------------------------
  1457. Name:        tmpfile
  1458.  
  1459. Synopsis:   FILE *tmpfile()
  1460.  
  1461. Function:   Creates a temporary stream file.
  1462.  
  1463. Return:     A pointer to the new stream file, or NULL if an error occurs.
  1464.  
  1465. See Also:   tmpnam
  1466. -------------------------------------------------------------------------
  1467. Name:        tmpnam
  1468.  
  1469. Synopsis:   #include "stdio.h"
  1470.         char *tmpnam(buf)
  1471.         char *buf;
  1472.  
  1473. Function:   Creates a string that is not the name of an existing file.
  1474.  
  1475. Arguments:  buf - buffer to store the string in. This buffer must be at
  1476.         least L_tmpnam characters long. If this argument is NULL then
  1477.         a pointer to a "static" string is returned. This string may be
  1478.         over-written by other calls to cclib.library functions, so
  1479.         it is best to make a local copy of the string or immediatly
  1480.         open a file using this string.
  1481.  
  1482. Return:     buf, or a pointer to the "static" area of memory used by tmpnam.
  1483.         The "static" memory is really located in the task_UserData
  1484.         structure for your process.
  1485.  
  1486. See Also:   tmpfile
  1487. -------------------------------------------------------------------------
  1488. Name:        ungetc
  1489.  
  1490. Synopsis:   short ungetc(c,fp)
  1491.         short c;
  1492.         FILE *fp;
  1493.  
  1494. Function:   Pushes a single character 'c' back into a stream file where it
  1495.         will be read as the next character of input. c may not be EOF.
  1496.  
  1497. Arguments:  c - character to put
  1498.         fp - stream to push into
  1499.  
  1500. Return:     The character puched back is returned, EOF on error.
  1501.  
  1502. See Also:   getc
  1503. -------------------------------------------------------------------------
  1504. Name:        vfprintf
  1505.  
  1506. Synopsis:   long vfprintf(fp,fmt,arg)
  1507.         FILE *fp;
  1508.         char *fmt;
  1509.         va_list arg;
  1510.  
  1511. Function:   Works the same as fprintf except that the variable argument
  1512.         list has been replaced by arg, which is a pointer into the
  1513.         stack. vfprintf is useful for implementing your own functions
  1514.         that use variable argument lists. Here is an example of a
  1515.         function you could write using a variable number of arguments:
  1516.  
  1517.         yourfprintf(fp,ymsg,fmt,arg)
  1518.         FILE *fp;
  1519.         char *ymsg, *fmt;
  1520.         int arg;
  1521.         {
  1522.         fprintf(fp,"Your Message: %s ",ymsg);
  1523.         vfprintf(fp,fmt,(va_list)&arg);
  1524.         }
  1525.  
  1526.         You could call this function like this:
  1527.  
  1528.         yourfprintf(fp,"Oops","%s %d","The number was",10);
  1529.  
  1530.         And the output would be:
  1531.  
  1532.         Your Message: Oops The number was 10
  1533.  
  1534. Arguments:  fp - pointer to stream
  1535.         fmt - format string, see printf for a complete discription
  1536.         arg - pointer to the first argument in a variable argument list
  1537.  
  1538. Return:     The number of characters written is returned, or negative
  1539.         if an error occured.
  1540.  
  1541. See Also:   printf
  1542. -------------------------------------------------------------------------
  1543. Name:        vprintf
  1544.  
  1545. Synopsis:   long vprintf(fmt,arg)
  1546.         char *fmt;
  1547.         va_list arg;
  1548.  
  1549. Function:   Works the same as printf except that the variable argument
  1550.         list has been replaced by arg, which is a pointer into the
  1551.         stack. See vfprintf to find out how to use arg.
  1552.  
  1553. Arguments:  fmt - format string, see printf for a complete discription
  1554.         arg - pointer to the first argument in a variable argument list
  1555.  
  1556. Return:     The number of characters written is returned, or negative
  1557.         if an error occured.
  1558.  
  1559. See Also:   printf, vfprintf
  1560. -------------------------------------------------------------------------
  1561. Name:        vsprintf
  1562.  
  1563. Synopsis:   long vsprintf(buf,fmt,arg)
  1564.         char *buf, *fmt;
  1565.         va_list arg;
  1566.  
  1567. Function:   Works the same as sprintf except that the variable argument
  1568.         list has been replaced by arg, which is a pointer into the
  1569.         stack. See vfprintf to find out how to use arg.
  1570.  
  1571. Arguments:  fmt - format string, see printf for a complete discription
  1572.         arg - pointer to the first argument in a variable argument list
  1573.  
  1574. Return:     The number of characters written is returned, or negative
  1575.         if an error occured.
  1576.  
  1577. See Also:   printf, vfprintf
  1578. -------------------------------------------------------------------------
  1579.  
  1580.    3) NON-STANDARD AND LOW-LEVEL I/O FUNCTIONS. Many of these functions
  1581.       have become widely used and must be supported even though they are not
  1582.       part of the ANSI standard C library.
  1583.  
  1584. -------------------------------------------------------------------------
  1585. Name:        access
  1586.  
  1587. Synopsis:   long access(fname,mode)
  1588.         char *fname;
  1589.         long mode;
  1590.  
  1591. Function:   Tells if a file or directory can be used for a particular
  1592.         purpose.
  1593.  
  1594. Arguments:  fname - the name of the file or directory.
  1595.         mode - asks for a certain type of access for the file or
  1596.         directory. mode = 4 (read access), 2 = write access, 1 =
  1597.         executable program, 0 = test for existance of the file.
  1598.  
  1599. Return:     Zero is returned if the requested accecc rights can be granted,
  1600.         otherwise -1 is retuned.
  1601.  
  1602. See Also:
  1603. -------------------------------------------------------------------------
  1604. Name:        close
  1605.  
  1606. Synopsis:   long close(fd)
  1607.         long fd;
  1608.  
  1609. Function:   Closes the specified low-level file.
  1610.  
  1611. Arguments:  fd - the descriptor for the low-level file obtained from
  1612.         open().
  1613.  
  1614. Return:     Zero is returned if the close was successful, -1 is returned if
  1615.         an error occured.
  1616.  
  1617. See Also:   open
  1618. -------------------------------------------------------------------------
  1619. Name:        creat
  1620.  
  1621. Synopsis:   long creat(fname,mode)
  1622.         char *fname;
  1623.         long mode;
  1624.  
  1625. Function:   creats a new file called 'fname'. This function is equivalent to:
  1626.         open(fname, O_WRONLY|O_TRUNC|O_CREAT, mode).
  1627.  
  1628. Arguments:  fname - the name of the file to create.
  1629.  
  1630. Return:     A file descriptor that can be used by the low-level I/O
  1631.         functions is returned. If an error occurs -1 is returned.
  1632.  
  1633. See Also:   open
  1634. -------------------------------------------------------------------------
  1635. Name:        fileno                 MACRO
  1636.  
  1637. Synopsis:   #include "stdio.h"
  1638.         long fileno(fp)
  1639.         FILE *fp;
  1640.  
  1641. Function:   Gets the low-level file descriptor for a stream file. This is
  1642.         most commonly used on non-bufferd streams such as stdin, stdout
  1643.         and stderr.
  1644.  
  1645. Arguments:  fp - stream file pointer
  1646.  
  1647. Return:     The file descrioptor for the stream file is returned.
  1648. -------------------------------------------------------------------------
  1649. Name:        isatty
  1650.  
  1651. Synopsis:   long isatty(fd)
  1652.         long fd;
  1653.  
  1654. Function:   Determines if a file descriptor is attached to an interactive
  1655.         device (virtual terminal) such as CON: or RAW:.
  1656.  
  1657. Arguments:  fd - file descriptor returned from open etc.
  1658.  
  1659. Return:     Non-zero is retuned if the file descriptor is an interactive
  1660.         device.
  1661. -------------------------------------------------------------------------
  1662. Name:        lseek
  1663.  
  1664. Synopsis:   long lseek(fd,offset,origin)
  1665.         long fd;
  1666.         long offset;
  1667.         unsigned long origin;
  1668.  
  1669. Function:   Sets the current position in a file.
  1670.  
  1671. Arguments:  fd - file descriptor for the file.
  1672.         offset - number of bytes to position the file from the origin.
  1673.         origin - 0 is beginning of the file, 1 is current position,
  1674.         2 is end of the file.
  1675.  
  1676. Return:     The new position in the file, or -1 on error.
  1677.  
  1678. See Also:   fseek
  1679. -------------------------------------------------------------------------
  1680. Name:        open
  1681.  
  1682. Synopsis:   #include "fcntl.h"
  1683.         long open(fname,flag,mode)
  1684.         char *fname;
  1685.         long flag;
  1686.         long mode;
  1687.  
  1688. Function:   Opens a file for low-level I/O.
  1689.  
  1690. Arguments:  fname - name of the file to open, may include path name as well.
  1691.         flag - specifies how the file is to be opened. The acceptable
  1692.         values (listed in fcntl.h) are listed below:
  1693.  
  1694.         O_RDONLY    -  open for reading only
  1695.         O_WRONLY    -  open for writing only
  1696.         O_RDWR    -  open for reading and writing
  1697.         O_CREAT    -  open the file after creating it
  1698.         O_TRUNC    -  remove contents then open the file
  1699.         O_EXCL    -  open fails if the file exists or'd with O_CREAT
  1700.         O_APPEND    -  open for appending only
  1701.  
  1702.         These flags may be or'd together to giver further meanings,
  1703.         for example:
  1704.  
  1705.         O_WRONLY|O_TRUNC - open for writing, nuke existing files
  1706.         O_RDWR|O_APPEND - open for reading and appending
  1707.  
  1708. Return:     fd - descriptor for the open file. This file descriptor is
  1709.         really a pointer to a FileDesc structure that is defined in
  1710.         iolib.h. The FileDesc structure is linked into the OpenFiles
  1711.         list attached to the task_UserData structure for your process.
  1712.         This is so that the library can close all of your open files
  1713.         before your process is terminated.
  1714.  
  1715. See Also:   close
  1716. -------------------------------------------------------------------------
  1717. Name:        read
  1718.  
  1719. Synopsis:   long read(fd,buf,size)
  1720.         long fd;
  1721.         char *buf;
  1722.         long size;
  1723.  
  1724. Function:   Reads bytes from a low-level file.
  1725.  
  1726. Arguments:  fd - file descriptor for the low-level file
  1727.         buf - buffer to store the data read from the file
  1728.         size - number of bytes to read
  1729.  
  1730. Return:     The number of bytes read is returned, -1L is returned on error
  1731.         or end of file. errno will be set on an error.
  1732.  
  1733. See Also:   open, write
  1734. -------------------------------------------------------------------------
  1735. Name:        unlink
  1736.  
  1737. Synopsis:   long unlink(fname)
  1738.         char *fname;
  1739.  
  1740. Function:   Deletes a file.
  1741.  
  1742. Arguments:  fname - name of the file to delete
  1743.  
  1744. Return:     Non-zero is returned on error.
  1745.  
  1746. See Also:   remove
  1747. -------------------------------------------------------------------------
  1748. Name:        write
  1749.  
  1750. Synopsis:   long write(fd,buf,n)
  1751.         long fd;
  1752.         char *buf;
  1753.         long n;
  1754.  
  1755. Function:   Low-level write to a file.
  1756.  
  1757. Arguments:  fd - low-level file descriptor obtained from open.
  1758.         buf - buffer to write
  1759.         n - number bytes to write
  1760.  
  1761. Return:     The number of bytes actually written, which may be less than n,
  1762.         is returned. -1 is returned on error.
  1763.  
  1764. See Also:   open, read
  1765. -------------------------------------------------------------------------
  1766.  
  1767.    4) CHARACTER TEST MACROS. All of these macros are defined in the
  1768.       file "ctype.h". They access a static array that is located in
  1769.       cclib.library. At initialization time a pointer is taken to this
  1770.       static array and that pointer is used for the characher test macros.
  1771.       Because the array is located in shared memory it would be unwise to
  1772.       change it's contents.
  1773.  
  1774. -------------------------------------------------------------------------
  1775.    #include "ctype.h"
  1776.  
  1777.    All of the macros take a character or integral value as an argument and
  1778.    "return" an int that is non-zero if the test passes.
  1779.  
  1780.     isalpha(c)  -  a letter a-z or A-Z
  1781.     isupper(c)  -  upper case letter A-Z
  1782.     islower(c)  -  lower case letter a-z
  1783.     isdigit(c)  -  decimal digit 0-9
  1784.     isxdigit(c) -  hexadecimal digit 0-9 or a-f or A-F
  1785.     isalnum(c)  -  alphanumeric 0-9 or a-z or A-Z
  1786.     isspace(c)  -  space, formfeed, newline, carrige return, tab, v-tab
  1787.     ispunct(c)  -  printing character except space letter or digit
  1788.     iscntrl(c)  -  control character
  1789.     isprint(c)  -  printable character spece included
  1790.     isgraph(c)  -  printing character except space
  1791.     isascii(c)  -  member of the ASCII character set
  1792.  
  1793.     The following macros don't do character tests but character conversions
  1794.     and are commonly found in ctype.h. The "return" values are the converted
  1795.     character.
  1796.  
  1797.     toascii(c)  -  converts a character to ASCII
  1798.     tolower(c)  -  converts upper case letters to lower case
  1799.     toupper(c)  -  converts lower case letters to upper case
  1800.  
  1801. -------------------------------------------------------------------------
  1802.  
  1803.    5) STRING FUNCTIONS. These functions operate on NULL terminated
  1804.       strings. A NULL terminated string is an array of type char
  1805.       whose last element is '\0' (zero).
  1806.  
  1807. -------------------------------------------------------------------------
  1808. Name:        bcpl_strcpy
  1809.  
  1810. Synopsis:   char *bcpl_strcpy(str,bstr)
  1811.         char *str;
  1812.         BSTR *bstr;
  1813.  
  1814. Function:   Copies a BCPL string into a C string. BCPL is the language that
  1815.         much of Amiga DOS was written in, and strings are different.
  1816.         First BCPL adresses only point to long words so... ptr =
  1817.         bcpl_ptr << 2 and BCPL strings start with a character count and
  1818.         then the number of characters in the string. This function is
  1819.         provided so that you can access strings in Amiga DOS data
  1820.         structures.
  1821.  
  1822. Arguments:  str - pointer to the character array where the BCPL string is
  1823.         to be placed.
  1824.         bstr - BCPL pointer to a BCPL string.
  1825.  
  1826. Return:     str is returned.
  1827. -------------------------------------------------------------------------
  1828. Name:        index
  1829.  
  1830. Synopsis:   char *index(str,c)
  1831.         char *str;
  1832.         short c;
  1833.  
  1834. Function:   Finds the first occurence of a character in a string.
  1835.  
  1836. Arguments:  str - string to search
  1837.         c - character to search for
  1838.  
  1839. Return:     A pointer to the found character or NULL if the character
  1840.         was not found.
  1841.  
  1842. See Also:   strchr
  1843. -------------------------------------------------------------------------
  1844. Name:        rindex
  1845.  
  1846. Synopsis:   char *rindex(str,c)
  1847.         char *str;
  1848.         short c;
  1849.  
  1850.  
  1851. Function:   Finds the last occurence of a character in a string.
  1852.  
  1853. Arguments:  str - string to search
  1854.         c - character to search for
  1855.  
  1856. Return:     A pointer to the found character of NULL if the character
  1857.         was not found.
  1858.  
  1859. See Also:   strrchr
  1860. -------------------------------------------------------------------------
  1861. Name:        stpcrlf
  1862.  
  1863. Synopsis:   char stpcrlf(str)
  1864.         char *str;
  1865.  
  1866. Function:   Strips carriage return of linefeed characters from a string.
  1867.         At the first encounter of a '\r' or '\n' character that
  1868.         character is replaced by a '\0' (NULL terminator.
  1869.  
  1870. Arguments:  str - string to strip
  1871.  
  1872. Return:     str is returned
  1873. -------------------------------------------------------------------------
  1874. Name:        strcat
  1875.  
  1876. Synopsis:   char *strcat(dest,source)
  1877.         char *dest;
  1878.         char *source;
  1879.  
  1880. Function:   Concatenates two strings. The destination string is assumed to
  1881.         be long enough to hold the concatenation.
  1882.  
  1883. Arguments:  dest - string to concatenate onto
  1884.         source - string to concatenate from
  1885.  
  1886. Return:     dest, the result, is returned
  1887.  
  1888. See Also:   strcpy
  1889. -------------------------------------------------------------------------
  1890. Name:        strchr
  1891.  
  1892. Synopsis:   char *strchr(str,c)
  1893.         char *str;
  1894.         short c;
  1895.  
  1896. Function:   Finds the first occurence of a character in a string.
  1897.  
  1898. Arguments:  str - string to search
  1899.         c - character to search for
  1900.  
  1901. Return:     A pointer to the found character or NULL if the character
  1902.         was not found.
  1903. -------------------------------------------------------------------------
  1904. Name:        strcmp
  1905.  
  1906. Synopsis:   short strcmp(str1,str2)
  1907.         char *str1, *str2;
  1908.  
  1909. Function:   Compares two strings.
  1910.  
  1911. Arguments:  str1, str2 - strings to compare
  1912.  
  1913. Return:     Negative is returned if str1 < str2, zero is returned if
  1914.         str1 == str2, positive is returned if str1 > str2.
  1915.  
  1916. See Also:   strncmp, strcmpa
  1917. -------------------------------------------------------------------------
  1918. Name:        strcmpa
  1919.  
  1920. Synopsis:   char *strcmpa(str1,str2)
  1921.         char *str1, *str2;
  1922.  
  1923. Function:   Compares two strings, ignoring the case of the letters. For
  1924.         example: 0 == strcmpa("BOB","bob");
  1925.  
  1926. Arguments:  str1, str2 - strings to compare
  1927.  
  1928. Return:     Negative is returned if str1 < str2, zero is returned if
  1929.         str1 == str2, positive is returned if str1 > str2.
  1930.  
  1931. See Also:   strncmp, strcmp
  1932. -------------------------------------------------------------------------
  1933. Name:        strcpy
  1934.  
  1935. Synopsis:   char *strcpy(dest,source)
  1936.         char *dest, *source;
  1937.  
  1938. Function:   Copies one string onto another, the NULL terminator is copied.
  1939.  
  1940. Arguments:  dest - destination string
  1941.         source - source string
  1942.  
  1943. Return:     dest is returned
  1944.  
  1945. See Also:   strncpy
  1946. -------------------------------------------------------------------------
  1947. Name:        strcspn
  1948.  
  1949. Synopsis:   long strcspn(str,reject)
  1950.         char *str, *reject;
  1951.  
  1952. Function:   Finds the length of a string not consisting of characters
  1953.         in another string.
  1954.  
  1955. Arguments:  str - string to search
  1956.         reject - string of characters that str is searched for
  1957.  
  1958. Return:     Length of prefix of str consisting of characters NOT in reject.
  1959.  
  1960. See Also:   strspn
  1961. -------------------------------------------------------------------------
  1962. Name:        strerror
  1963.  
  1964. Synopsis:   char *strerror(err)
  1965.         long err;
  1966.  
  1967. Arguments:  err - an error code, usually the global variable errno
  1968.  
  1969. Return:     Returns a string corresponding to an error number.
  1970. -------------------------------------------------------------------------
  1971. Name:        strlen
  1972.  
  1973. Synopsis:   long strlen(str)
  1974.         char *str;
  1975.  
  1976. Function:   Computes the length of string.
  1977.  
  1978. Arguments:  str - string to compute the length of
  1979.  
  1980. Return:     Length of the string
  1981. -------------------------------------------------------------------------
  1982. Name:        strncat
  1983.  
  1984. Synopsis:   char *strncat(dest,source,n)
  1985.         char *dest, *source;
  1986.         long n;
  1987.  
  1988. Function:   Concatenates up to n characters onto dest from source.
  1989.  
  1990. Arguments:  dest - destination string
  1991.         source - source string
  1992.         n - maximum number of characters to concatenate
  1993.  
  1994. Return:     dest is returned.
  1995.  
  1996. See Also:   strcat
  1997. -------------------------------------------------------------------------
  1998. Name:        strncmp
  1999.  
  2000. Synopsis:   short strncmp(str1,str2,n)
  2001.         char *str1, *str2;
  2002.         long n;
  2003.  
  2004. Function:   Compare at most n characters of two strings.
  2005.  
  2006. Arguments:  str1, str2 - strings to compare
  2007.         n - maximum number of characters to copy
  2008.  
  2009. Return:     Negative is returned if str1 < str2, zero is returned if
  2010.         str1 == str2, positive is returned if str1 > str2.
  2011.  
  2012. See Also:   strcmpa, strcmp
  2013. -------------------------------------------------------------------------
  2014. Name:        strncpy
  2015.  
  2016. Synopsis:   char *strncpy(dest,source,n)
  2017.         char *dest, *source;
  2018.         long n;
  2019.  
  2020. Function:   Copies at most n characters from source to dest. The string is
  2021.         NULL terminated.
  2022.  
  2023. Arguments:  dest - destination string
  2024.         source - source string
  2025.         n - maximum number of characters to copy
  2026.  
  2027. Return:     dest is returned
  2028.  
  2029. See Also:   strcpy
  2030. -------------------------------------------------------------------------
  2031. Name:        strnrv
  2032.  
  2033. Synopsis:   char *strnrv(str,n)
  2034.         char *str;
  2035.         long n;
  2036.  
  2037. Function:   Reverses at most n characters of a string. For example
  2038.         strnrv("Hello World",5) => "olleH World".
  2039.  
  2040. Arguments:  str - string to reverse
  2041.         n - maximum length of the string to reverse
  2042.  
  2043. Return:     str is returned
  2044.  
  2045. See Also:   strrv
  2046. -------------------------------------------------------------------------
  2047. Name:        strpbrk
  2048.  
  2049. Synopsis:   char *strpbrk(str,search)
  2050.         char *str, *search;
  2051.  
  2052. Function:   Searches for one of a string of characters in a string.
  2053.  
  2054. Arguments:  str - string to search
  2055.         search - string of characters to search for
  2056.  
  2057. Return:     A pointer to the first character of str belonging to search is
  2058.         returned, if no match is found NULL is returned.
  2059.  
  2060. See Also:   strspn
  2061. -------------------------------------------------------------------------
  2062. Name:        strrchr
  2063.  
  2064. Synopsis:   char *strrchr(str,c)
  2065.         char *str;
  2066.         short c;
  2067.  
  2068. Function:   Finds the last occurence of a character in a string.
  2069.  
  2070. Arguments:  str - string to search
  2071.         c - string to search for
  2072.  
  2073. Return:     A pointer to the last occurence of c in str is returned, if
  2074.         no match is found NULL is returned.
  2075.  
  2076. See Also:   strchr
  2077. -------------------------------------------------------------------------
  2078. Name:        strrv
  2079.  
  2080. Synopsis:   char *strrv(str)
  2081.         char *str;
  2082.  
  2083. Function:   Reverses the characters in a string. For example:
  2084.         strrv("Kasak") => "kasaK"
  2085.  
  2086. Arguments:  str - string to reverse
  2087.  
  2088. Return:     str is returned
  2089.  
  2090. See Also:   strnrv
  2091. -------------------------------------------------------------------------
  2092. Name:        strspn
  2093.  
  2094. Synopsis:   long strspn(str,search)
  2095.         char *str, *search;
  2096.  
  2097. Function:   Finds the length of a string consisting of characters
  2098.         in another string.
  2099.  
  2100. Arguments:  str - string to search
  2101.         search - string of characters that str is searched for
  2102.  
  2103. Return:     Length of prefix of str consisting of characters in search.
  2104.  
  2105. See Also:   strcspn
  2106. -------------------------------------------------------------------------
  2107. Name:        strstr
  2108.  
  2109. Synopsis:   char *strstr(str,search)
  2110.         char *str;
  2111.         char *search;
  2112.  
  2113. Function:   Finds a string in another string.
  2114.  
  2115. Arguments:  str - string to search
  2116.         search - string to search for
  2117.  
  2118. Return:     Returns a pointer to the string in str that matches search,
  2119.         if the string is not found NULL is returned.
  2120. -------------------------------------------------------------------------
  2121. Name:        strtok
  2122.  
  2123. Synopsis:   char *strtok(str,delim)
  2124.         char *str;
  2125.         char *delim;
  2126.  
  2127. Function:   A sequence of calls splits the string str into tokens, each
  2128.         delimited by a character in delim. The first call to strtok
  2129.         must be with a non-NULL str argument. The argument is remembered
  2130.         by strtok for subsequent calls. The first token is found by
  2131.         searching for characters not in delim. When a token is found
  2132.         the character just after the token is over-written with a NULL
  2133.         and a pointer to the token is returned. Each subsequent call to
  2134.         strtok, indicated by a NULL str argument, will return the next
  2135.         token in str. NULL is returned when there are no further tokens
  2136.         in str.
  2137.  
  2138. Arguments:  str - string to split tokens out of
  2139.         delim - string consisting of legal delimiters
  2140.  
  2141. Return:     Tokens split out from the string are returned, or NULL when
  2142.         there are no more tokens in the string.
  2143. -------------------------------------------------------------------------
  2144. Name:        strupr
  2145.  
  2146. Synopsis:   char *strupr(str)
  2147.         char *str;
  2148.  
  2149. Function:   Converts a string to all upper case letters.
  2150.  
  2151. Arguments:  str - string to convert
  2152.  
  2153. Return:     str is returned
  2154. -------------------------------------------------------------------------
  2155.  
  2156.       6) MEMORY OPERATION FUNCTIONS. These functiuons have become common
  2157.      for most implementations of the C library. They all operate
  2158.      on blocks of memory of a certain size instead of null terminated
  2159.      strings as with the string functions.
  2160.  
  2161. -------------------------------------------------------------------------
  2162. Name:        bcpm
  2163.  
  2164. Synopsis:   short bcmp(ptr1,ptr2,size)
  2165.         void *ptr1, *ptr2;
  2166.         long size;
  2167.  
  2168. Function:   Compares two blocks of memory.
  2169.  
  2170. Arguments:  ptr1, ptr2 - pointers to two blocks of memory to compare
  2171.         size - maximum number of bytes to compare
  2172.  
  2173. Return:     Negative is returned if ptr1 > ptr2, zero is returned if
  2174.         ptr1 == ptr2, positive is returned if ptr1 < ptr2.
  2175.  
  2176. See Also:   memcmp
  2177. -------------------------------------------------------------------------
  2178. Name:        bcopy
  2179.  
  2180. Synopsis:   void bcopy(source,dest,size)
  2181.         void *source, *dest;
  2182.         long size;
  2183.  
  2184. Function:   Copies a block of memory making sure that overlapping blocks
  2185.         are copied correctly.
  2186.  
  2187. Arguments:  source - pointer to source block of memory
  2188.         dest - pointer to destination block of memory
  2189.         size - number of bytes to copy
  2190.  
  2191. See Also:   memcpy
  2192. -------------------------------------------------------------------------
  2193. Name:        bzero
  2194.  
  2195. Synopsis:   void bzero(ptr,size)
  2196.         void *ptr;
  2197.         long size;
  2198.  
  2199. Function:   Sets a block of memory to all zeros.
  2200.  
  2201. Arguments:  ptr - pointer to block of memory
  2202.         size - number of bytes to set to zero
  2203.  
  2204. See Also:   memset
  2205. -------------------------------------------------------------------------
  2206. Name:        memccpy
  2207.  
  2208. Synopsis:   void *memccpy(dest,source,stop,size)
  2209.         void *dest, *source;
  2210.         unsigned short stop;
  2211.         long size;
  2212.  
  2213. Function:   Copies a block of memory until a certain byte is reached or
  2214.         until the maximum number of bytes is reached.
  2215.  
  2216. Arguments:  dest - pointer to block of memory to copy to
  2217.         source - pointer to block of memory to copy from
  2218.         stop - if the stop character is encoutered then the copy
  2219.         operation is stopped after the stop character is copied to
  2220.         the destination block.
  2221.         size - maximum number of bytes to copy
  2222.  
  2223. Return:     If the stop character is encountered then a pointer to the
  2224.         next byte after the stop character is returned, if the stop
  2225.         character is never encounterd then NULL is returned.
  2226. -------------------------------------------------------------------------
  2227. Name:        memchr
  2228.  
  2229. Synopsis:   void *memchr(ptr,chr,size)
  2230.         void *ptr;
  2231.         unsigned short chr;
  2232.         long size;
  2233.  
  2234. Function:   Finds a character in a block of memory.
  2235.  
  2236. Arguments:  ptr - block of memory to search
  2237.         chr - character to search for
  2238.         size - maximum number of bytes to search
  2239.  
  2240. Return:     If the character is found then a pointer to it is returned.
  2241.         NULL is returned if the character is not found.
  2242. -------------------------------------------------------------------------
  2243. Synopsis:   short memcmp(ptr1,ptr2,size)
  2244.         void *ptr1, *ptr2;
  2245.         long size;
  2246.  
  2247. Function:   Compares two blocks of memory.
  2248.  
  2249. Arguments:  ptr1, ptr2 - pointers to two blocks of memory to compare
  2250.         size - maximum number of bytes to compare
  2251.  
  2252. Return:     Negative is returned if ptr1 < ptr2, zero is returned if
  2253.         ptr1 == ptr2, positive is returned if ptr1 > ptr2.
  2254. -------------------------------------------------------------------------
  2255. Name:        memcpy
  2256.  
  2257. Synopsis:   void *memcpy(dest,source,size)
  2258.         void *dest, *source;
  2259.         long size;
  2260.  
  2261. Function:   Copies a block of memory making sure that overlapping blocks
  2262.         are copied correctly.
  2263.  
  2264. Arguments:  dest - pointer to destination block of memory
  2265.         source - pointer to source block of memory
  2266.         size - number of bytes to copy
  2267.  
  2268. Return:     dest is returned
  2269. -------------------------------------------------------------------------
  2270. Name:        memmove                 MACRO
  2271.  
  2272. Synopsis:   #include "string.h"
  2273.         void *memmove(dest,source,size)
  2274.         void *dest, *source;
  2275.         long size;
  2276.  
  2277. Function:   Copies a block of memory making sure that overlapping blocks
  2278.         are copied correctly.
  2279.  
  2280. Arguments:  dest - pointer to destination block of memory
  2281.         source - pointer to source block of memory
  2282.         size - number of bytes to copy
  2283.  
  2284. Return:     dest is returned
  2285. -------------------------------------------------------------------------
  2286. Name:        memset
  2287.  
  2288. Synopsis:   void *memset(ptr,chr,long)
  2289.         void *ptr;
  2290.         unsigned short chr;
  2291.         long size;
  2292.  
  2293. Function:   Sets all bytes in a block of memory to a single value.
  2294.  
  2295. Arguments:  ptr - pointer to a block of memory
  2296.         chr - value to set each byte to
  2297.         size - number of bytes to set
  2298.  
  2299. Return:     ptr is returned
  2300. -------------------------------------------------------------------------
  2301. Name:        memswap
  2302.  
  2303. Synopsis:   void memswap(ptr1,ptr2,size)
  2304.         void *ptr1, *ptr2;
  2305.         long size;
  2306.  
  2307. Function:   Swaps the contents of two blocks of memory.
  2308.  
  2309. Arguments:  ptr1, ptr2 - blocks of memory to swap
  2310.         size - number of bytes to swap
  2311. -------------------------------------------------------------------------
  2312.  
  2313.       7) FORMAT CONVERSION FUNCTIONS. Conversions from numbers to
  2314.      ASCII characters and back.
  2315.  
  2316. -------------------------------------------------------------------------
  2317. Name:        atof
  2318.  
  2319. Synopsis:   double atof(str)
  2320.         char *str;
  2321.  
  2322. Function:   Converts a character string representing a floating point number
  2323.         into an IEEE format double precision floating pointer number.
  2324.  
  2325. Arguments:  str - string to convert
  2326.  
  2327. Return:     A floating point number, zero is returned if no conversion can
  2328.         be made.
  2329. -------------------------------------------------------------------------
  2330. Name:        atoi
  2331.  
  2332. Synopsis:   short atoi(str)
  2333.         char *str;
  2334.  
  2335. Function:   Converts a string representing an integer into a short integer.
  2336.  
  2337. Arguments:  str - string to convert
  2338.  
  2339. Return:     A short integer, zero is returned if no conversion can be made.
  2340.  
  2341. See Also:   stoa
  2342. -------------------------------------------------------------------------
  2343. Name:        atol
  2344.  
  2345. Synopsis:   long atol(str)
  2346.         char *str;
  2347.  
  2348. Function:   Converts a string representing an integer into a long integer.
  2349.  
  2350. Arguments:  str - string to convert
  2351.  
  2352. Return:     A long integer, zero is returned if no conversion can be made.
  2353.  
  2354. See Also:   ltoa
  2355. -------------------------------------------------------------------------
  2356. Name:        ltoa
  2357.  
  2358. Synopsis:   void ltoa(n,str)
  2359.         long n;
  2360.         char *str;
  2361.  
  2362. Function:   Converts a long integer into a string.
  2363.  
  2364. Arguments:  n - number to convert
  2365.         str - string to store the result in
  2366.  
  2367. See Also:   atol
  2368. -------------------------------------------------------------------------
  2369. Name:        stoa
  2370.  
  2371. Synopsis:   void ltoa(n,str)
  2372.         short n;
  2373.         char *str;
  2374.  
  2375. Function:   Converts a short integer into a string.
  2376.  
  2377. Arguments:  n - number to convert
  2378.         str - string to store the result in
  2379.  
  2380. See Also:   atoi
  2381. -------------------------------------------------------------------------
  2382.  
  2383.       8) MEMORY ALLOCATION FUNCTIONS. These functions include the standard
  2384.       heap managment functions as well as lower level functions that were
  2385.       used to implement the heap managment system. When the program that
  2386.       has allocated memory through the functions in this section terminates
  2387.       execution through the exit function all memory allocated from Amiga
  2388.       DOS is returned to the system. All of the heap managment functions
  2389.       will try to allocate memory first from FAST memory and then from CHIP
  2390.       RAM. To allocate memory that is guaranteed to be CHIP RAM (accesable
  2391.       by the Amiga custom chips) you can use the _alloc() function. The
  2392.       heap manager operates by allocating blocks of memory from Amiga DOS
  2393.       in large chunks, then it breaks these blocks up into the sizes that
  2394.       are requested through heap memory allocation functions. The minimum
  2395.       size of the blocks allocated from Amiga DOS can be controlled
  2396.       directly by declaring a global long integer called blocksize and
  2397.       setting it to some value. The default value for blocksize is 256
  2398.       blocks (2K bytes), in increments of 8 bytes. Each time the heap
  2399.       manager allocates memory from Amiga DOS the blocksize variable is
  2400.       checked, which makes it possible to change the variable on the fly.
  2401.  
  2402. -------------------------------------------------------------------------
  2403. Name:        be_free
  2404.  
  2405. Synopsis:   void be_free(ptr,size)
  2406.         void *ptr;
  2407.         long size;
  2408.  
  2409. Function:   Makes static memory available to malloc and calloc. If you have
  2410.         static data structures that will NEVER be used as such again
  2411.         then you can add them to the free memory list with this
  2412.         function. If you write into the data pointed to by ptr after
  2413.         you have added that block to the free memory list then you
  2414.         stand a good chance of corrupting the free memory list. When the
  2415.         free memory list for your task is corrupt the system will
  2416.         when you try to access it with calloc, malloc, or free.
  2417.  
  2418.  
  2419. Arguments:  ptr - pointer to the block of memory to give to the heap
  2420.         manager.
  2421.         size - size of the block of memory
  2422. -------------------------------------------------------------------------
  2423. Name:        calloc
  2424.  
  2425. Synopsis:   void *calloc(nobj,size)
  2426.         unsigned long nobj, size;
  2427.  
  2428. Function:   Allocates and sets to zero an area of memory that is at least
  2429.         nobj * size bytes. This is a standard C function.
  2430.  
  2431. Arguments:  nobj - number of objects to allocate
  2432.         size - size of each object to allocate
  2433.  
  2434. Return:     A pointer to the newly allocated block of memory. NULL is
  2435.         returned when the block of memory can't be provided.
  2436.  
  2437. See Also:   malloc
  2438. -------------------------------------------------------------------------
  2439. Name:        free
  2440.  
  2441. Synopsis:   free(ptr)
  2442.         void *ptr;
  2443.  
  2444. Function:   Returns a block of memory allocated through malloc, calloc or
  2445.         realloc to the heap manager for future use. This is a
  2446.         standard C function.
  2447.  
  2448. Arguments:  ptr - pointer to the block of memory obtained from malloc, calloc
  2449.         or realloc.
  2450.  
  2451. See Also:   be_free
  2452. -------------------------------------------------------------------------
  2453. Name:        freeall
  2454.  
  2455. Synopsis:   freeall()
  2456.  
  2457. Function:   Returns ALL of the memory allocated by any of the functions
  2458.         in this section to the system and re-initializes the free
  2459.         memory list for the heap manager. This will also free all of
  2460.         the memory used by any files that may be open. Normally this
  2461.         function is only called when the program has called the exit
  2462.         function.
  2463. -------------------------------------------------------------------------
  2464. Name:        heap_alloc
  2465.  
  2466. Synopsis:   void *heap_alloc(size)
  2467.         long size;
  2468.  
  2469. Function:   Allocates memory from the heap manager. This function is
  2470.         used internally to implement malloc and calloc.
  2471.  
  2472. Arguments:  size - size in bytes of the requested block of memory
  2473.  
  2474. Return:     A pointer to the newly allocated block of memory. NULL is
  2475.         returned when the block of memory can't be provided.
  2476.  
  2477. See Also:   malloc, calloc
  2478. -------------------------------------------------------------------------
  2479. Name:        heap_free
  2480.  
  2481. Synopsis:   void heap_free(ptr)
  2482.         void *ptr;
  2483.  
  2484. Function:   Returns memory to the free list of the heap manager. This
  2485.         function is used internally to implement free().
  2486.  
  2487. Arguments:  ptr - pointer to a block of memory obtained from heap_alloc.
  2488.  
  2489. See Also:   free
  2490. -------------------------------------------------------------------------
  2491. Name:        malloc
  2492.  
  2493. Synopsis:   void *malloc(size)
  2494.         unsigned long size;
  2495.  
  2496. Function:   Allocates memory from the heap manager that is at least
  2497.         "size" bytes. This is a standard C function.
  2498.  
  2499. Arguments:  size - size of the requested block of memory
  2500.  
  2501. Return:     A pointer to the newly allocated block of memory. NULL is
  2502.         returned when the block of memory can't be provided.
  2503.  
  2504. See Also:   free
  2505. -------------------------------------------------------------------------
  2506. Name:        malloc_size
  2507.  
  2508. Synopsis:   unsigned long malloc_size(ptr)
  2509.         void *ptr;
  2510.  
  2511. Function:   Computes the number of bytes in an allocated block of memory
  2512.         that was obtained from malloc, calloc, realloc, or heap_alloc.
  2513.         The size is rounded up to the nearest eight bytes.
  2514.  
  2515. Arguments:  ptr - a pointer to the allocated block of memory.
  2516.  
  2517. Return:     The size of the allocated block is returned.
  2518. -------------------------------------------------------------------------
  2519. Name:        realloc
  2520.  
  2521. Synopsis:   void *realloc(ptr,newsize)
  2522.         void *ptr;
  2523.         unsigned long newsize;
  2524.  
  2525. Function:   Changes the size of a block block of memory. The contents will
  2526.         be un-changed up to the minimum of the old and new sizes. The
  2527.         block of memory can be freed using free() prior to a call to
  2528.         realloc so long as no intervening calls to any of the heap
  2529.         managment functions is made. In order to make enough space
  2530.         for a larger block of memory is may be necessary to move the
  2531.         block. This is a standard C function.
  2532.  
  2533. Arguments:  ptr - pointer to the block of memory to change the size of
  2534.  
  2535. Return:     A pointer to the new block of memory is returned or NULL if the
  2536.         request can't be satisfied.
  2537.  
  2538. See Also:   free
  2539. -------------------------------------------------------------------------
  2540. Name:        sbrk
  2541.  
  2542. Synopsis:   void *sbrk(size)
  2543.         unsigned long size;
  2544.  
  2545. Function:   Allocates memory through Amiga DOS and attaches the block
  2546.         of memory to the allocated memory list for the current task.
  2547.         This is a lower level function than the heap managment
  2548.         functions. The sbrk function has become a standard part of many
  2549.         C libraries.
  2550.  
  2551. Arguments:  size - size in bytes of the requested block of memory
  2552.  
  2553. Return:     A pointer to the newly allocated block of memory is returned, or
  2554.         -1L if the request can't be satisfied.
  2555. -------------------------------------------------------------------------
  2556. Name:        _alloc
  2557.  
  2558. Synopsis:   void _alloc(ud,size,requirements)
  2559.         task_UserData *ud;
  2560.         long size;
  2561.         long requirements;
  2562.  
  2563. Function:   Allocates memory from Amiga DOS and links it into the allocated
  2564.         memory list for your task. This is the lowest level of memory
  2565.         allocation available through this library and is used to
  2566.         implement all of the other memory allocation functions. The
  2567.         task_UserData pointer can be obtained by a call to GetSTDIO.
  2568.  
  2569. Arguments:  ud - pointer to the task_UserData structure for your task
  2570.         size - size in bytes of the memory to be allocated
  2571.         requirements - memory requirements as described in
  2572.         exec/memory.h, 0L being just any old block of memory.
  2573.         The requirements are used directly in a call to the Amiga
  2574.         AllocMem function.
  2575.  
  2576. Return:     A pointer to the new block of memory is returned or NULL if the
  2577.         request can't be satisfied.
  2578.  
  2579. See Also:   _fre
  2580. -------------------------------------------------------------------------
  2581. Name:        _fre
  2582.  
  2583. Synopsis:   void _fre(ud,ptr)
  2584.         task_UserData *ud;
  2585.         void *ptr;
  2586.  
  2587. Function:   Frees a block of memory allocated by _alloc or sbrk.
  2588.         The task_UserData pointer can be obtained by a call to GetSTDIO.
  2589.  
  2590. Arguments:  ud - pointer to the task_UserData structure for your task
  2591.         ptr - pointer to a block of memory obtained from _alloc or sbrk.
  2592. -------------------------------------------------------------------------
  2593. Name:        _freall
  2594.  
  2595. Synopsis:   void _freall(ud)
  2596.         task_UserData *ud;
  2597.  
  2598. Function:   Returns all memory allocated by through any of the functions
  2599.         in this section to Amiga DOS, but does NOT re-initialize the
  2600.         free list used by the heap manager. The task_UserData pointer
  2601.         can be obtained by a call to GetSTDIO.
  2602.  
  2603. Arguments:  ud - pointer to the task_UserData structure for your task
  2604. -------------------------------------------------------------------------
  2605.  
  2606.       9) LINKED LIST FUNCTIONS. Linked lists are used internally in
  2607.       CClib.library and since the linked list functions are already
  2608.       in the library they were made public. The structure definitions
  2609.       for linked lists and nodes are in stdlist.h.
  2610.  
  2611. -------------------------------------------------------------------------
  2612. Name:        add_head
  2613.  
  2614. Synopsis:   void *add_head(l,size)
  2615.         _list *l;
  2616.         long size;
  2617.  
  2618. Function:   Allocates and clears to zero memory from the heap manager for
  2619.         a _node structure plus "size" bytes. The node is then added
  2620.         to the beginning of the linked list.
  2621.  
  2622. Arguments:  l - linked list to add to
  2623.         size - size in bytes of the data for this node
  2624.  
  2625. Return:     A pointer to the data for this node is returned, or NULL if
  2626.         there is not enough memory.
  2627.  
  2628. See Also:   remv_node
  2629. -------------------------------------------------------------------------
  2630. Name:        add_tail
  2631.  
  2632. Synopsis:   void *add_tail(l,size)
  2633.         _list *l;
  2634.         long size;
  2635.  
  2636. Function:   Allocates and clears to zero memory from the heap manager for
  2637.         a _node structure plus "size" bytes. The node is then added
  2638.         to the end of the linked list.
  2639.  
  2640. Arguments:  l - linked list to add to
  2641.         size - size in bytes of the data for this node
  2642.  
  2643. Return:     A pointer to the data for this node is returned, or NULL if
  2644.         there is not enough memory.
  2645.  
  2646. See Also:   remv_node
  2647. -------------------------------------------------------------------------
  2648. Name:        inst_node
  2649.  
  2650. Synopsis:   _node *inst_node(size)
  2651.         long size;
  2652.  
  2653. Function:   Allocates and clears to zero memory from the heap manager for
  2654.         a _node structure plus "size" bytes. This function is used
  2655.         by all of the functions that create a new node.
  2656.  
  2657. Arguments:  size - size in bytes of the data for this node
  2658.  
  2659. Return:     A pointer to the new node is returned, or NULL if there isn't
  2660.         enough memory.
  2661. -------------------------------------------------------------------------
  2662. Name:        put_head
  2663.  
  2664. Synopsis:   void put_head(l,n)
  2665.         _list *l;
  2666.         _node *n;
  2667.  
  2668. Function:   Adds a node at the beginning of a linked list.
  2669.  
  2670. Arguments:  l - linked list to add to
  2671.         n - node to add to the linked list
  2672.  
  2673. See Also:   remv_head
  2674. -------------------------------------------------------------------------
  2675. Name:        put_tail
  2676.  
  2677. Synopsis:   void put_tail(l,n)
  2678.         _list *l;
  2679.         _node *n;
  2680.  
  2681. Function:   Adds a node at the end of a linked list.
  2682.  
  2683. Arguments:  l - linked list to add to
  2684.         n - node to add to the linked list
  2685.  
  2686. See Also:   remv_tail
  2687. -------------------------------------------------------------------------
  2688. Name:        remv_head
  2689.  
  2690. Synopsis:   void *remv_head(l,data)
  2691.         _list *l;
  2692.         void **data;
  2693.  
  2694. Function:   Removes a node from the beginning of a linked list and gives
  2695.         a pointer to the data for that node. The memory for the
  2696.         node is not freed.
  2697.  
  2698. Arguments:  l - linked list to remove from
  2699.         data - pointer to a memory location where a pointer to the
  2700.         data for the node will be stored after removing the node
  2701.         from the beginning of the list
  2702.  
  2703. Return:     A pointer to the block of memory that was allocated for the
  2704.         node and its data is returned, or NULL if there are no more
  2705.         nodes on the list. This memory should be freed using the
  2706.         free function. For example:
  2707.         _list *l;
  2708.         char *data, *ptr;
  2709.         .
  2710.         .
  2711.         .
  2712.         if( ptr = remv_head(l,&data) )
  2713.            free(ptr)
  2714.  
  2715. See Also:   add_head
  2716. -------------------------------------------------------------------------
  2717. Name:        remv_list
  2718.  
  2719. Synopsis:   void remv_list(l)
  2720.         _list *l;
  2721.  
  2722. Function:   Frees all memory associated with a linked list by calling
  2723.         free for every nide in the list and then for the list
  2724.         header.
  2725.  
  2726. Arguments:  l - linked list to free, it is assumed that all of the nodes
  2727.         on the list and the list header itself are allocated using
  2728.         heap_alloc, malloc, calloc, or realloc.
  2729. -------------------------------------------------------------------------
  2730. Name:        remv_node
  2731.  
  2732. Synopsis:   void *remv_node(l,data)
  2733.         _list *l;
  2734.         void *data;
  2735.  
  2736. Function:   Removes a node from a list by first scanning the list for the
  2737.         data associated with the node and then removing the node from
  2738.         the list.
  2739.  
  2740. Arguments:  l - pointer to the list to remove the node from.
  2741.         data - pointer to the data associated with the node to be
  2742.         removed
  2743.  
  2744. Return:     A pointer to the memory allocated for the node and it's data
  2745.         is returned, NULL is returned if the node with the specified
  2746.         data can't be found on the list. The pointer can then be used
  2747.         to free the node and it's data, for example:
  2748.         if( ptr = remv_node(l,data) )
  2749.            free(ptr);
  2750. -------------------------------------------------------------------------
  2751. Name:        remv_tail
  2752.  
  2753. Synopsis:   void *remv_tail(l,data)
  2754.         _list *l;
  2755.         void **data;
  2756.  
  2757. Function:   Removes a node from the end of a linked list and gives
  2758.         a pointer to the data for that node. The memory for the
  2759.         node is not freed.
  2760.  
  2761. Arguments:  l - linked list to remove from
  2762.         data - pointer to a memory location where a pointer to the
  2763.         data for the node will be stored after removing the node
  2764.         from the end of the list
  2765.  
  2766. Return:     A pointer to the block of memory that was allocated for the
  2767.         node and its data is returned, or NULL if there are no more
  2768.         nodes on the list. This memory should be freed using the
  2769.         free function.
  2770.  
  2771. See Also:   add_tail
  2772. -------------------------------------------------------------------------
  2773. Name:        r_node
  2774.  
  2775. Synopsis:   void *r_node(l,n,data)
  2776.         _list *l;
  2777.         _node *n;
  2778.         void **data;
  2779.  
  2780. Function:   Removes a specific node from a linked list and gives a pointer
  2781.         to the data for the node.
  2782.  
  2783. Arguments:  l - linked list to remove the node from
  2784.         n - node to remove from the list
  2785.         data - a pointer to the data for this node is stored here
  2786.  
  2787. Return:     n is returned, or NULL if the list is empty
  2788.  
  2789. See Also:   remv_node
  2790. -------------------------------------------------------------------------
  2791.  
  2792.       10) SORTING FUNCTIONS, these are all modifications of
  2793.       C. A. R. Hoare's quicksort algorithm. Two of the functions
  2794.       are written in C and a third is written in 68000 assembler
  2795.       for speed.
  2796.  
  2797. -------------------------------------------------------------------------
  2798. Name:        qsort
  2799.  
  2800. Synopsis:   void qsort(base,n,size,cmp)
  2801.         void *base;
  2802.         unsigned long n, size;
  2803.         short (*cmp)();
  2804.  
  2805. Function:   Sorts into ascending order an array base[0]...base[n-1] of
  2806.         objects of size "size".
  2807.  
  2808. Arguments:  base - pointer to the first element in the array of elements
  2809.         tp sort.
  2810.         n - number of elements to sort
  2811.         size - size of each element of the array
  2812.         cmp - pointer to comparison function. The comparison function
  2813.         is passed a pointer to two elements of the array and returns
  2814.         zero if the two elements are equivalent, negative must be
  2815.         returned if the first element is less than the second and
  2816.         and positive must be returned if the first element is greater
  2817.         than the second. To sort in the opposite order negative is
  2818.         returned if the first element is greater than the second and
  2819.         positive is returned if the first element is less than the
  2820.         second. Here is an example of a comparison function that
  2821.         will sort strings in descending order:
  2822.  
  2823.         short cmp(str1,str2)
  2824.         char *str1, *str2;
  2825.         {
  2826.         return( strcmp(str2,str1) );
  2827.         }
  2828.  
  2829. -------------------------------------------------------------------------
  2830. Name:        quicksort
  2831.  
  2832. Synopsis:   void quicksort(n,comp,swap,ptr)
  2833.         unsigned long n;
  2834.         short (*comp)();
  2835.         void (*swap)();
  2836.         void *ptr;
  2837.  
  2838. Function:   The quicksort function uses the same sorting algorithm as
  2839.         qsort but it is designed to sort anything, not just arrays
  2840.         in memory.
  2841.  
  2842. Arguments:  n - number of elements to sort.
  2843.         comp - comparison function. The comparison function is passed
  2844.         the index of the two elements to compare and an auxilery
  2845.         pointer that you provide. It returns zero if the two elements
  2846.         are equivalent, negative must be returned if the first element
  2847.         is less than the second and and positive must be returned if
  2848.         the first element is greater than the second. To sort in the
  2849.         opposite order negative is returned if the first element is
  2850.         greater than the second and positive is returned if the first
  2851.         element is less than the second.
  2852.         swap - swaps two elements. The swap function is passed the
  2853.         index of the two elements to swap and an auxilery pointer you
  2854.         provide.
  2855.         ptr - auxilery pointer, can point to anything. This variable
  2856.         is passed to the comp and swap functions in order to facilitate
  2857.         the writing of re-entrant code.
  2858.  
  2859. -------------------------------------------------------------------------
  2860. Name:        vquicksort
  2861.  
  2862. Synopsis:   void vquicksort(n,comp,swap)
  2863.         unsigned short n;
  2864.         short (*comp();
  2865.         void (*swap)();
  2866.  
  2867. Function:   The vquicksort function is much the same as the quicksort
  2868.         function except that only up to 64K elements can be sorted
  2869.         and there is no auxilery argument pointer. Vquicksort is
  2870.         written in 100% hand optomized assembly language, hence it's
  2871.         name, very quicksort.
  2872.  
  2873. Arguments:  n - number of elements to sort.
  2874.         comp - comparison function. The comparison function is passed
  2875.         the index of the two elements to compare. It returns zero if
  2876.         the two elements are equivalent, negative must be returned if
  2877.         the first element is less than the second and and positive must
  2878.         be returned if the first element is greater than the second. To
  2879.         sort in the opposite order negative is returned if the first
  2880.         element is greater than the second and positive is returned if
  2881.         the first element is less than the second.
  2882.         swap - swaps two elements. The swap function is passed the
  2883.         index of the two elements to swap.
  2884.  
  2885. See Also:   quicksort
  2886. -------------------------------------------------------------------------
  2887.  
  2888.       11) TIME FUNCTIONS. These are the standard time functions as
  2889.       described in K&R edition II. Most of these functions use typedefs
  2890.       and structure definitions that are found in time.h. The tm structure
  2891.       is explained here.
  2892.  
  2893.       struct tm
  2894.       {
  2895.       short tm_sec;    seconds after the minute
  2896.       short tm_min;    minutes after the hour
  2897.       short tm_hour;    hours since midnight
  2898.       short tm_mday;    day of the month
  2899.       short tm_mon;    months since January
  2900.       short tm_year;    years since 1900
  2901.       short tm_wday;    days since sunday
  2902.       short tm_yday;    days since January, 1
  2903.       short tm_isdst;    Not Used
  2904.       };
  2905.  
  2906. -------------------------------------------------------------------------
  2907. Name:        asctime
  2908.  
  2909. Synopsis:   char *asctime(tm)
  2910.         struct tm *tm;
  2911.  
  2912. Function:   Converts the time in the structure tm to a string of the
  2913.         form: Sun Jan 1 12:00:00 1989
  2914.  
  2915. Arguments:  tm - structure obtained from localtime
  2916.  
  2917. Return:     A pointer to a string is returned. The string is in "static"
  2918.         memory and may be overwritten by other calls.
  2919.  
  2920. See Also:   localtime
  2921. -------------------------------------------------------------------------
  2922. Name:        clock
  2923.  
  2924. Synopsis:   clock_t clock()
  2925.  
  2926. Function:   Obtains the number of ticks since program execution.
  2927.  
  2928. Return:     The number of ticks that have passed since the program was
  2929.         first executed is returned. clock()/CLOCK_TCK gives the time
  2930.         in seconds.
  2931. -------------------------------------------------------------------------
  2932. Name:        ctime
  2933.  
  2934. Synopsis:   char *ctime(t)
  2935.         time_t *t;
  2936.  
  2937. Function:   Equivalent to asctime(localtime(t)).
  2938.  
  2939. Arguments:  t - pointer to a time_t obtained from time().
  2940.  
  2941. Return:     A pointer to a string is returned. The string is in "static"
  2942.         memory and may be overwritten by other calls.
  2943.  
  2944. See Also:   asctime, localtime, time
  2945. -------------------------------------------------------------------------
  2946. Name:        difftime
  2947.  
  2948. Synopsis:   long difftime(t1,t2)
  2949.         time_t t1, t2;
  2950.  
  2951. Function:   Obtains the difference between two times in seconds.
  2952.         t2 - t1.
  2953.  
  2954. Arguments:  t1, t2 - times to take the difference of
  2955.  
  2956. Return:     Time difference in seconds.
  2957.  
  2958. See Also:   time
  2959. -------------------------------------------------------------------------
  2960. Name:        gmtime
  2961.  
  2962. Synopsis:   struct tm *gmtime(t)
  2963.         time_t *t;
  2964.  
  2965. Function:   Same as localtime because Coordinated Universal Time is not
  2966.         readily available on the amiga.
  2967.  
  2968. Arguments:  t - pointer to a time_t obtained from time().
  2969.  
  2970. Return:     Same as localtime.
  2971. -------------------------------------------------------------------------
  2972. Name:        localtime
  2973.  
  2974. Synopsis:   struct tm *localtime(t)
  2975.         time_t *t;
  2976.  
  2977. Function:   Fills out a tm structure from the time obtained from time().
  2978.  
  2979. Arguments:  t - pointer to a time_t obtained from time().
  2980.  
  2981. Return:     A tm structure is returned. This structure is located in
  2982.         "static" memory and will be overwritten by later calls. For
  2983.         an explanation of the tm structure see the heading for this
  2984.         section.
  2985.  
  2986. See Also:   time
  2987. -------------------------------------------------------------------------
  2988. Name:        mktime
  2989.  
  2990. Synopsis:   time_t mktime(tm)
  2991.         struct tm *tm;
  2992.  
  2993. Function:   This function is the opposite of localtime, it converts a
  2994.         tm structure into a time_t.
  2995.  
  2996. Arguments:  tm - pointer to a tm structure
  2997.  
  2998. Return:     A time_t that can be used by the other time functions is
  2999.         returned.
  3000. -------------------------------------------------------------------------
  3001. Name:        strftime
  3002.  
  3003. Synopsis:   size_t strftime(s,smax,fmt,tm)
  3004.         char *s;
  3005.         size_t smax;
  3006.         char *fmt;
  3007.         struct tm *tm;
  3008.  
  3009. Function:   Formats date and time information into a string according to
  3010.         a format string.
  3011.  
  3012. Arguments:  s - string to store the result
  3013.         smax - maximum number of characters to place in the string
  3014.         fmt - format string, ordinary characters including the NULL
  3015.         terminator are copied to the result string. Format specifiers
  3016.         have the the following possible values:
  3017.  
  3018.            %a    abbreviated weekday name
  3019.            %A    full weekday name
  3020.            %b    abbreviated month name
  3021.            %B    full month name
  3022.            %c    local date and time representation
  3023.            %d    day of the month
  3024.            %H    hour, 24 hour clock
  3025.            %I    hour, 12 hour clock
  3026.            %j    day of the year, 1-366
  3027.            %m    month, 1-12
  3028.            %M    minute, 00-59
  3029.            %p    AM or PM
  3030.            %S    second 00-59
  3031.            %U    week number of year 00-53
  3032.            %w    weekday, 0-6
  3033.            %W    same as U
  3034.            %x    local date representation
  3035.            %X    local time representation
  3036.            %y    year without century
  3037.            %Y    year with century
  3038.            %Z    "Local"
  3039.            %%    '%'
  3040.  
  3041. Return:     The number of characters written excluding the NULL terminator
  3042.         is returned, zero is returned if the result string would be
  3043.         overflowed.
  3044. -------------------------------------------------------------------------
  3045. Name:        time
  3046.  
  3047. Synopsis:   time_t time(t)
  3048.         time_t *t;
  3049.  
  3050. Function:   Obtains the current time, if the t argument is not NULL then
  3051.         the time is also assigned to *t.
  3052.  
  3053. Arguments:  t - pointer to variable to store the current time, or NULL.
  3054.  
  3055. Return:     The current time is returned.
  3056. -------------------------------------------------------------------------
  3057.  
  3058.       IV) INSTALLATION
  3059.  
  3060.    In order to use CClib.library you will first have to install the
  3061.    provided header files in a directory. Some of these header files
  3062.    have the same name as the ones used by your C and you will have to
  3063.    make sure that the CClib.library header files are found first. The
  3064.    best way to assure this is to use the -I or -i option of the compiler.
  3065.    When using floating point you will have to use the +FI or -fi options
  3066.    to ensure that IEEE floating point numbers are used, and you will
  3067.    have to link with the appropriate IEEE floating point library, ma.lib
  3068.    or lcmieee.lib. Before a prorgam that is linked with the CCLib.library
  3069.    can execute properly you must copy the file CCLib.library into the
  3070.    libs: directory on your system disk.
  3071.  
  3072.              For Aztec C
  3073.    When you link your program you will have to make sure that it gets
  3074.    linked in this order: _main.o yourstuff.o ... cclib.lib.... It would
  3075.    also be a good idea to look at the makefile for the test program;
  3076.    test.mke.
  3077.  
  3078.             For Lattice C
  3079.    When you link your program you will have to make sure that it gets
  3080.    linked in this order: cc.o lcmain.o yourstuff.o ... lcclib.lib.... It
  3081.    would also be a good idea to look at the makefile for the test program;
  3082.    test.lmk.
  3083.  
  3084.  
  3085. -------------------------------------------------------------------------
  3086.  
  3087.       V) THE NUKELIB PROGRAM
  3088.  
  3089.       The nukelib program is used to remove a library from memory. The
  3090.       syntax of the program is very simple;
  3091.  
  3092.       NukeLib <library name>
  3093.  
  3094.       for example:
  3095.  
  3096.       NukeLib CClib.library
  3097.  
  3098.       This will clear CClib.library from memory if no applications are using
  3099.       it at the time.
  3100.  
  3101. -------------------------------------------------------------------------
  3102.  
  3103.       VI) RELEASE INFORMATION
  3104.  
  3105.       This release contains:
  3106.  
  3107.       cclib.doc     This Documentation
  3108.       cclib.lib     Aztec 3.6 compatable library of connection routines
  3109.             (small code and data )
  3110.       cclibl.lib    (large code and data )
  3111.       lcclib.lib    Lattice 5.02 library of connection routines
  3112.       CClib.library    The loadable Amiga C library
  3113.       nukelib        Utility program deletes libraries from memory
  3114.       loc        Utility program counts lines of C code
  3115.       test        Test program, (written in Aztec)
  3116.       _main.o        Aztec  _main replacement
  3117.       lcmain.o        Lattice _main replacement
  3118.       cc.o        Modified Lattice startup routine
  3119.  
  3120.       source (dir)      Source code directory
  3121.      test.c        test program
  3122.      loc.c           utility counts lines of C
  3123.      test.mke       Aztec makefile
  3124.      loc.mke       Aztec makefile
  3125.      test.lmk       Lattice makefile
  3126.      _main.c       Aztec _main routine
  3127.      lcmain.c       Lattice _main routine
  3128.  
  3129.       include (dir)     Include files required for CClib.library
  3130.      alloc.h assert.h ccfunc.h ctype.h
  3131.      errno.h fcntl.h heapmem.h iolib.h
  3132.      limits.h stat.h stdarg.h stdio.h
  3133.      stdlib.h stdlist.h string.h time.h
  3134.  
  3135.       con.zoo         Source for connection routine library
  3136.  
  3137.            Contents of con.zoo ...
  3138.  
  3139.           Actual Connection routines
  3140.        102.con 108.con 114.con 120.con 126.con 132.con
  3141.        138.con 144.con 150.con 156.con 162.con 168.con
  3142.        172.con 180.con 186.con 192.con 198.con 204.con
  3143.        210.con 216.con 222.con 228.con 234.con 240.con
  3144.        246.con 252.con 258.con 264.con 270.con 276.con
  3145.        282.con 288.con 294.con 30.con 300.con 306.con
  3146.        312.con 318.con 324.con 330.con 336.con 342.con
  3147.        348.con 354.con 36.con 360.con 366.con 372.con
  3148.        378.con 384.con 390.con 396.con 402.con 408.con
  3149.        414.con 42.con 420.con 426.con 432.con 438.con
  3150.        444.con 450.con 456.con 462.con 468.con 474.con
  3151.        48.con 480.con 486.con 492.con 498.con 504.con
  3152.        510.con 516.con 522.con 528.con 534.con 54.con
  3153.        540.con 546.con 552.con 558.con 564.con 570.con
  3154.        576.con 582.con 588.con 594.con 60.con 600.con
  3155.        606.con 612.con 618.con 624.con 630.con 636.con
  3156.        642.con 648.con 654.con 66.con 660.con 666.con
  3157.        672.con 678.con 684.con 690.con 696.con 702.con
  3158.        714.con 72.con 720.con 726.con 732.con 738.con
  3159.        744.con 750.con 756.con 762.con 768.con 774.con
  3160.        78.con 780.con 786.con 792.con 798.con 804.con
  3161.        810.con 816.con 822.con 84.con 90.con 96.con
  3162.  
  3163.        all.con       Concatenation of connection routines
  3164.        blocksize.c       Contains blocksize global variable
  3165.        cclib.mke       Aztec makefile for library (small code and data)
  3166.        cclibl.mke       Aztec makefile for library (large code and data)
  3167.        cclib.lmk       Lattice makefile for library
  3168.        libfile       Command file for Lattice librarian
  3169.        mclibcon.i       Metacomco Assembler include file
  3170.        aclibcon.i       Aztec Assembler include file
  3171.        lclibcon.i       Lattice Assembler include file
  3172.        cclibcon.i       Aztec Assembler include file
  3173.        math.c       Contains _math global variable
  3174.  
  3175. -------------------------------------------------------------------------
  3176.       VII) NOTES ON LATTICE C
  3177.  
  3178.       There is now full support for the Lattice compiler. However due to
  3179.       some unforseen complications the Lattice startup code had to be
  3180.       changed in order for this to work. There is an object module called
  3181.       cc.o that should be used as the replacement for the standard Lattice
  3182.       startup routine (c.o).
  3183.  
  3184.       The specific problem with the startup code was this: For programs
  3185.       that were executed from the CLI the Lattice startup code would place
  3186.       the name of the program into the commnad string that was passed to
  3187.       _main and since CCLib.library already does this for you it was
  3188.       unnecessary to do this in the startup code. The symptoms of the
  3189.       problem were that argv[0] and argv[1] were both set to the name of
  3190.       the program. The problem with Workbench programs was far more
  3191.       serious, the Lattice startup code would reply to the workbench
  3192.       message after CClib.library had already done so, causing a system
  3193.       crash.
  3194.  
  3195.       Because of copyright problems the source for the modified c.a (cc.a)
  3196.       can't be included here, but since the only changes are commented out
  3197.       lines, I will list which lines were commented out. If you wish you
  3198.       may want to do this to c.a so that you have the source to the startup
  3199.       code. The lines commented out of c.a are: 189-198, 201-206, 227-229,
  3200.       247-283, and 323-336. In addition the label 'main' on line 283 was
  3201.       moved to line 284.
  3202.  
  3203.       If you are doing any floating point in your program it is best to use
  3204.       IEEE floating point numbers. This is supported by the -fi compiler
  3205.       switch and lcmieee.lib. This will give you the advantage of extra
  3206.       speed if you run on a machine with a math coprocessor. IEEE is the
  3207.       only type used by CCLib.library.
  3208.  
  3209.       There are new makefiles used for the Lattice compiler. All of the
  3210.       Lattice makefiles end with .lmk, where the Aztec makefiles end
  3211.       with .mke.
  3212.  
  3213.       Lattice 5 supports function prototypes where Aztec 3.6a does not.
  3214.       The CCLib.library include files can use function prototypes if the
  3215.       symbol ANSIC is defined. Be sure to include the CCLib.Library
  3216.       include files ahead of the standard Lattice and Amiga include files.
  3217.  
  3218.       Thanks to Kevin Kenny for help in creating the Lattice version of
  3219.       the connection routines and startup code.
  3220.  
  3221. -------------------------------------------------------------------------
  3222.  
  3223.       VIII) REVISION HISTORY
  3224.  
  3225.        Version numbers only change when the file CClib.library
  3226.        changes.
  3227.  
  3228.     8/89 - V1.0 Initial release, beta testing.
  3229.  
  3230.     9/89 - V1.1 Major bug fixes, documentation released, extensive testing,
  3231.        time functions added, nukelib program added.
  3232.  
  3233.    10/89 - V1.1 Release 2 Support for Lattice C added,
  3234.        doumentation improvements.
  3235.  
  3236.    10/89 - V1.2 A bug was fixed where programs that were executed from the
  3237.        workbench with no tooltype of the form
  3238.        WINDOW=CON:10/10/100/100/Title would fail because the startup
  3239.        code had required that standard I/O be opened. Now for workbench
  3240.        programs with no CON: window the standard I/O will not be opened.
  3241.  
  3242.    10/89 - V1.3 A bug in the quicksort function was fixed. The auxilery
  3243.        argument is now passed correctly to the swap function as well
  3244.        as the comp function. CClibl.lib was added to support large
  3245.        code and data in Aztec C. LOC a C code line counting program
  3246.        was added.
  3247.  
  3248. -------------------------------------------------------------------------
  3249.  
  3250.       IX) COPYRIGHTS AND TRADEMARKS
  3251.  
  3252.       Aztec C is a trademark of Manx Software Systems.
  3253.       Lattice C is a trademark of Lattice Inc.
  3254.       Amiga is a trademark of Commodore Business Machines Inc.
  3255.  
  3256. -------------------------------------------------------------------------
  3257.  
  3258.